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SECTION 1 


Significant Differences 


The following list summarizes the significant differences between 
FlexOS 1.42 and FlexOS 1.31: 


O The installation process has been automated through the use of 
batch files. 


O An new installation option is. offered. The LOADFLEX.EXE 
command enables users to install FlexOS in a DOS partition, then 
start FlexOS from the DOS command line (see the Installation 
Instructions). 


O The hard disk driver has been rewritten to improve performance. 
This new driver also allows partitions greater than 32Mb to be 
made bootable, and partitions other than the first one can be 
made bootable. 


Note: The new hard disk driver ts renamed from ATHD.DRV to 
HD DRV. 


O The FDISK utility has been rewritten to support the new hard disk 
driver. See the Configuration Guide for information about FDISK. 


O The floppy disk driver now implements door open detection to 
support AT-style drives (see Section 6). 


O Large-model SRIL’s (Shareable Run-time Libraries) are now 
supported and the documentation has been improved (see Section 
11). 


O There is a separate stand-alone debugger supplied on diskette 
SBK 5. . 


O An optional on-line, menu-driven help system is now available. 


End of Section 1 
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Debug Disk 


The diskette labelled SBK 5 in the System Builder’s Kit contains 
SASID286, a stand-alone debugger (a debugger that is executable and 
runs on a separate terminal) for debugging driver code. In order to 
use SASID286, you must generate a version of FlexOS you can run and 
debug from another terminal. The FLEX286.MAK file generates a 
working copy of FlexOS. 


2.1 Using SASID386 


Before you begin to use SASID, make sure that you have another serial 
terminal attached to the COM2 port on your development system. 
SASID286 uses this terminal to display information about activity 
taking place on the standard terminal. 


Put diskette SBK 5 in drive A anid boot up the system. You wiil see 
the SASID286 prompt on the serial terminal screen. SASID286 is 
similar to the SID 286 debugger, described in the Programmer’s 
Utilities Guide, and shares many commands with it. Table 2-1 lists 
SASID286 commands. 


SASID286 also has built-in help. Simply press the question mark (?) to 
see a screen of help topics. Pressing two question marks gives you 
another screenful. 


2.1 Using SASID386 
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Table 2-1. SASID286 Commands 


Display Memory 


b<address>,<length>,<address > 
d<address>,<address> 
dw<address>,<address > 
diIw<address>,<offset>,<size> 
|< address,address > 
sr<address >,<length>,<value> 


Examine Memory 


s<address > 

sw<address > 
f<address>,<address> 
fw<address>,<address> 
m<address>,<length>,<value> 


Execute 


g<address>,<address >,< address > 
p<address>,<count>,<address> 
t<count> 

tw<count> 

u<count> 

X 

c<address>,parm,parm... 


Compare memory 

Display bytes 

Display words 

Display linked list by words 
Disassemble code 

Search for value 


Display and set bytes 
Display and set words 
Fill memory bytes 

Fill memory words 
Move memory block 


Go at address until break 
Set passpoint 

Trace instructions 

Trace without calls 

Trace without display 
Display registers 

Call a function 


Version 1.42 Release Notes 2.1 Using SASID386 


Table 2-1. (Continued) 


Miscellaneous 


h Display symbols 
h.symbol Display symbol offset 
<value > Hex-decimal conversion 
h<valuel>,<value2 > Hex arithmetic 
n<name>,<address > Add name to symbols 
qi<port> Input byte from port 
qiw<port> Input word from port 
qo<port> ~ Output byte to port 
qow <port> Output word to port 

V Primitive stack dump 


Note: A symbol or register can be used as an <address>. 


End of Section 2 
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SECTION 3 


Shared Memory 


3.1 Shared Memory Regions 


FlexOS allows multiple processes to share common memory regions. 
Processes can also access specific physical memory locations, for dual 
ported RAM or system ROMs, through the shared memory driver 
services. 


The processes can share data regions with drivers’ for fast 


communications in both protected and unprotected FlexOS 
environments, and multiple user processes can share data regions with 
each other. FlexOS grants access to shared memory only to those 
user processes with access rights established during system 
implementation. 


There are two ways to access shared memory; through shared 


memory files, which work like pines, and through the driver services 


SHMEM and UN SHMEM. 


Shared memory files are created with the CREATE SVC and have the 
“sm:" device name. A subsequent OPEN SVC provides and verifies 
access to the file. The GET SVC returns a valid address for the shared 


memory region, the CLOSE SVC disables access via this address, and 


DELETE releases the region. Each shared data file also contains a 
semaphore, so drivers and processes can synchronize usage through 
the READ and WRITE SVCs. 


ut 


The Pipe Resource Manager disallows an open request of “sm:" 
devices by any process with an rnid <> Q. This prevents a process 
on a remote node of a network from gaining access to shared data. 
Note that pipes are different in this respect: processes on one node 
Can access pipes on remote nodes. 


Figure 4-1 shows the SHMEM table that can be examined with the 
LOOKUP SVC. 


3.1 SHARED MEMORY REGIONS 
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3.2 Using Shared Memory Files 


Table 3-1. SHMEM Table Fields 


Field Description 

KEY Unique ID 

NAME Name 

RESERVED Must be 0 

SIZE Size of memory area in bytes 

SECURITY Security word 

USER User ID of creator 

GROUP Group ID of creator 

UBUFFER User address of shared memory. This value is zero 
if the table was obtained through the LOOKUP SVC. 
You must use GET to obtain the address. 

SBUFFER System address of shared memory. This value is 
used by drivers and system processes independent 
of process context. 

Device Type Ox11 

Device Name "sm." 


Table Number 0x11 


3.2 Using Shared Memory Files 


To create a shared memory region a user process performs the 
following calls: 


fnum = s_ create(0O, flags, "“sm:name", O, security, size); 
s get(T SHMEM, fnum, &shmem, sizeof (shmem) ) 
buff ptr = shmem.ubuffer; 


BUFF PTR now points to the shared memory. 
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If another user process wants to use the above shared memory file it 
performs the following calls: 


fFnum = s_open(flags, “sm:name"); 
s get(T SHMEM, fnum, &shmem, sizeof(shmem) ); 
buff ptril = shmem.ubuffer: 


All references to “BUFF PTR1 now access the named shared memory 
region. 


A driver could give a user process access to a ROM of length LENGTH 
at address PHYS ADDR by using the following calls: 


struct 
{ 

LONG link, pstart, plength; 
} phys _mem = { O01, PHYS ADDR, LENGTH }; 


sys _addr = (BYTE *)mapphys(&phys mem, 1); 


usr addr = shmem(sys_ addr, read only flag): 


The user process would then use a SPECIAL() or GET() call to receive 
the user buffer address from the driver. 


If two user processes need to synchronize access to a shared memory 
file they could each make the following calls: 


s read(0, fnum, “", O11, O1); /* Get exclusive access” */ 
critical code(); /* Perform critical code */ 
Ss wreitelO, frum, "". OT, -O1)% /* Release semaphore */ 


FNUM is the file number of the shared memory file obtained through 
the CREATE or OPEN calls. 


When it no longer needs access to the shared memory file, the user 
process makes the call: 


s close(0, fnum); 


FNUM is the file number that was attained by the CREATE or OPEN 
calls. 


If the driver wants to remove user access to the shared memory it 
created it makes the call: 


un shmem(usr_ addr); 


usr addr is the address obtained by the SHMEM() call. 
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3.3 Shared Memory Driver Services 


A shared memory driver service must be used for a new process to 
7 gain access to shared memory. The driver obtains system memory by 
( utilizing the MAPPHYS() or SALLOC() driver services, and then allows a 
user process access to memory through a SHMEM() driver service. 
The region is subsequently released with the UN SHMEM driver 
service. This gives a user process direct control of memory related 
devices. | 
Note: OEM's must write a shared memory driver to Support an 
application’s use of shared memory, but FlexOS' provides two 
subroutines that the driver can call. 


3.3.1 SHare MEMory 


The SHMEM driver service lets a user process address system memory 
while running in user space. 


BYTE Fuse addr , sys addr : 
UWORD flags: 


use adde = shmem(sys addr, flags); 

Parameters: 

flags bit 0: O = Read/Write buffer 
1 = Read Only buffer 


bits 1-15 are reserved 


sys addr System address obtained through SALLOC() or MAPPHYS() 


Return Code: 


usr addr User buffer address. 0 indicates failure 


30 
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3.3.2 UN SHare MEMory 


The UN SHMEM() driver service reverses the function of a previous 
SHMEM() call. After this call, the user process gets an exception if it 
tries to access shared memory. If the user process passes an address 
to UN SHMEM() that was not previously obtained through an SHMEM() 
call, it receives an error. 


LONG ret: 

BYTE Pus edt: 

ret = un_shmem(Cusr addr ); 
Parameters: 


usr addr User buffer address obtained through shmem() 


Return Code: 


ret0 indicated success; error code indicates bad usr addr 


End of Section 3 
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SECTION 4 


New Driver Service Calls 


FlexOS 286 contains two new driver services that are not documented 
in the System Guide. These driver services allow FlexOS to more 
efficiently exploit memory management units (MMUs), which support 
paging of physical memory. 


4.1 CSALLOC Driver Service 


In previous versions of FlexOS, when calling SALLOC to allocate 
memory in the system address space, a driver could rely on the fact 
that this memory was always physically contiguous, so external 
devices under the driver’s control such as DMA controllers which use 
physical addresses and bypass the MMU, would work properly. 


This assumption is no longer true. If the memory to be allocated must 
be physically contiguous, CSALLOC must be used instead of SALLOC. 
A bit in the flags parameter determines whether contiguity is required. 


The second reason for calling CSALLOC is to allocate memory which 
must be physically tsolated from other system buffers. This use of 
CSALLOC is to exert control over a buffer which may be passed (by 
the DOS Application Environment) to a user process. If the allocation 
for the Application Environment were in the same page as the 
allocation for an important system data structure, the user process 
would have the potential to corrupt system data. The “isolate” bit in 
the CSALLOC flags word is used to control this area of memory 
protection. Note: In FlexOS 386, an isolated buffer starts on a 4Kb 
boundary and the allocation extends in multiples of 4Kb. The Intel? 
80286 processor does not support the same sort of hardware mapping, 
So a setting of the ISOLATE bit on a call to CSALLOC in FlexOS 286 is 
ignored. 


C Interface for CSALLOC: 
sysadr = csalloc (length, flags); 


Parameters: 
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BYTE * sysadr; /* System address of memory block * / 
/* allocated. Q indicates no */ 
/* memory available. roe 
ULONG length; /* Number of bytes to allocate a 
UWORD flags; Pe BIS As 
1 = Physical contiguity required 
Q = Non-contiguity accepted 
Bad. ae 
1 = Physical isolation required 
QO = Not required 
Other bits must = 0. | m7, 
/*’salloc(length)’is ftinctionally equivalent to ‘csalloc(length,0)'*/ 


4.2 CONTIG Driver Service 


In previous versions of FlexOS, drivers that did DMA to and from 
physical memory addresses would call PADDR to convert the system 
address of the buffer to a physical address, with the driver assuming 
the whole buffer was physically contiguous starting from the address 
returned. In FlexOS 386, this assumption is no longer true. Therefore, 
CONTIG has been added to find the physical address of a buffer and 
the number of bytes that are physically contiguous from that point. 


C Interface: 


size = contig (buffer, length, &phyadr): 


Parameters: 
ULONG size; /* Number of bytes that are physically ae 
[i contiguous. sat 4 
BYTE * buffer; /* System address of buffer if 
ULONG length; /* Length (bytes) of buffer * / 
BYTE * phyadr,; /* Physical address of buffer (returned) */ 
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Version 1.42 Release Notes 4.2 CONTIG Driver Service 


The following conditions must be met before calling CONTIG for the 
first time for a given buffer: 


1. The owner of the buffer must be mapped into memory (MAPU). 


2. The buffer must have passed a MRANGE call. 


After finding the number of bytes that are contiguous in the buffer, the 
driver can do DMA to or from that portion of the buffer. Note that the 
physical address of the buffer is returned via ‘phyadr. If the return 
‘size is not equal to the ‘length’, then the buffer is not contiguous and 
more calls to CONTIG are required. For the next call, ‘length’ should 
be decreased by ‘size’, and the buffer address should be increased by 
‘size’. Then, assuming the process owning the buffer is still mapped 
in, another call to CONTIG can be made. Repeat this process until the 
returned ‘size’ and ‘length’ are the same. 


End of Section 4 
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SECTION 5 


Removeable Subdrivers 


FlexOS has the ability to remove subdrivers using the standard user 
DVRUNLK command and supervisor INSTALL function. A user can enter 
the subdriver device name in the DVRUNLK command to remove the 
subdriver from a driver. A programmer can use the INSTALL SVC with 
the option field set to 0 and the devname field set to the subdriver 
name address to remove a driver. 


Subdrivers like drivers are set as removable or permanent in INSTALL 
flag bit 5. When the bit is set, the subdriver is marked as removable; 
otherwise, it should not be removable. The DEVICE Table’s INSTAT 
field reflects the install status, whether permanent or removable. 


For subdrivers, the fields are defined as follows: 


0x00 - Not installed 

0x01 - Requires subdriver 

0x02 - Owned by Miscellaneous Resource Manager 
0x03 - Owned by another driver 

0x04 - Optional subdriver 


Drivers are informed to remove a subdriver through the SUBDRIVE 
function entry point. This entry point is now used both to associate 


and disassociate a subdriver. To indicate which operation to perform, 


bit 10 in the Access field is set as follows: 


Bit 10: O = Install subdriver 
1 Uninstall subdriver 


The remainder of the Access flags remain as defined in Table 4-4, 
INSTALL Flags in the FlexOS System Guide. 


The driver should then do whatever is necessary to remove the 
subdriver. Note, however, that the driver can ignore the request if the 
subdriver is Currently in use. The following sample code illustrates a 
SUBDRIVE routine that handles both installation and removal of the 
subdriver. 
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LONG s_ subdrvr(pb) 
DPB *ob; 
{ 

PHYSBLK a 


if(pb->dp flags & 0x400) { 
sfree(sdev[pb->dp_option|); 


sdev[pb->dp option] = Q; 
return((((LONG)DVR PORT << 16) | (LONG)DVR_SER)); 
} 
ser _unit|[pb->dp option] = pb->dp_unitno; 
pt hdri[pb->dp_unitno] = (DH *) pbh->dp_ swi; 
pester th pb edp aan tao) = “po -dp. option: 
gd = sdevi[pb--dp option] = 
(PHYSBLK *) salloc( (LONG)sizeof(PHYSBLK) ); 
d->Qrear = d--Qfront = d->evpend = 


d->xoffed = d--Qlen = Q; 


return(E SUCCESS); 
} 


The return code from the SUBDRIVE function should indicate the type 
of subdriver required or O, if no subdriver is required. 


Typically, the SUBDRIVE routine is not the only portion of the driver 
involved in the subdrive interface. For example, you should also free 
the resources such as flags, pipes and memory for data structures 
used to enable device 1/O when the remove command is received. 


As a general rule when removing subdrivers, everything done in INIT 
and SELECT to support device !/O should be undone in UNINIT and 
FLUSH, respectively. 


End of Section 5 
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SECTION 6 


Open Door Detection 


Section 8.1.2 of the System Guide describes the type of drives 
supported by the FlexOS Disk Resource Manager: 


@ non-removeable media (hard disk drive) 
@® removeable media with no door open support 
@® removable media with door open interrupt (DOI) support 


Beginning with release 1.42, the Disk Resource Manager supports a 
fourth type: removable media with door open detection (DOD). 


Drives that support removable media and do not support DOI incur 
high overhead since the Disk Resource Manager must periodically 


verify the media has not been changed. Door open detection provides 


support for removeable media without incurring high overhead. When 
the Disk Resource Manager decides to do a media check, it first 
checks the driver to determine if the door has been opened. If it has, 
the media is checked and then new media is logged in. 


Since performance on removeable media only (RMO) drives would be 
unacceptably degraded if a verify was done on each entry into the 
caching code, the driver can specify how often the media should be 
checked (see Section 6.2, “Media Timed Verification’). 


6.1 Driver support for DOD 
Beginning with release 1.42, the GET driver function call (see page 


8-46 in the System Guide is modified to support door open detection. 
Figure 6-1 shows the modified parameter block. 


6.1 Driver support for DOD Version 1.42 Release Notes 


GET--Provide unit-specific information 


Parameter: Address of GET parameter block 
Return Code: 


E SUCCESS Successful operation 


E_BADPB Bad parameter block 
0 1 Z 3 
lo ounrr |” FLAGS ti (asti(i‘séCOC~* 
ane “<= it <4 
i; «a. ADDR ti (twtst*~<‘CSC‘*d 
| MAXFATRECS = ~—*(|~—sMAXFATSIZ~—séd 
| MAXDIRSIZ ~=~«(|~—S~dDVRDELTAtC(t:*«C*YS; 


TS a RR AR ARNE eS TY IN i S| YY SY GN SEE SY i I NY eS aunen  o  eehe | ene 


Figure 6-1. GET Parameter Block 
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MAXRS 


ADDR 


6.1 Driver support for DOD > 


Table 6-1. GET Parameter Block Fields 


Description 


Driver unit number 
Reserved 


Type of disk medium 
Bit 0: 1 = Removable media only 
0 = Permanent media 
1 = Open door support enabled 
0 = Open door support diabled 
Bit 2: Reserved 
1 
0 
1 
0 


Bit 1: 


Bit 3: = Door open detection enabled 
= Door open detection disabled 
= Media timed verification enabled 
= Media timed verification disabled 


Bit 4: 


Maximum Record Size. This is the maximum physical 
sector size of all media types supported through this disk 
driver unit. For example, if this unit supports both single- 
and double-density diskettes, the larger of the physical 
sector sizes should be stated here. This field determines 
the size of the buffers the Disk Resource Manager 
maintains for the unit. 


Address of the open door byte if this is a disk drive with 
open-door- interrupt support. 


MAXFATRCS 


Maximum number of FAT records in a single FAT for all 
media types supported through this driver unit. 


MAXFATSIZE 


Maximum size of FAT, in bytes. 
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Table 6-1. (Continued) 


Field Description 


MAXDIRSIZE 
Maximum number of root directory entries. 


DVRDELTA Number of milliseconds to wait before performing media 
check if media hasn't been accessed. 


Disk drivers that Support door open detection should set the following 
bits in the dtype field: | 


bit 0 = on (Removable Media only) 
bit 3 = on (Door open detection enabled) 
bit 4 n (Media timed verification enabled) 


The driver must also support a new Special function as described 
below. The driver must check for an open door occurrence on all 
READ or WRITE calls and return E_LREADY if an open door is detected. 
After returning ELREADY once, the eival must return it again only 
when the condition reoccurs. 
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Special Function 4 -- Get Open door information 
Parameter: Address of SPECIAL parameter block 


Return Code: 


E SUCCESS Same media 
E_UNITNO Invalid unit number 
E_BADPB Bad parameter block 

E NEWMEDIA New media 

E DOOROPEN Door has been opened 


Figure 6-2. SPECIAL Function 4 Parameter Block 
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Table 6-2. SPECIAL Function 4 Parameter Block Fields 


Description 


Driver unit number 


Special function number (in hex) 


Bits 0-15 are reserved 


Special function 4 returns ELNEWMEDIA when the driver verifies there 
is new media in the drive. E_DOOROPEN is returned when there may 
be new media in the drive. 


On a E_DOOROPEN error, the Disk Resource Manager performs a media 
check to verify if there is new media in the drive. If there is new 
media, or E_NEWMEDIA was returned, the Disk Resource Manager 
performs a relog operation on the unit. Once the driver returns 
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EF NEWMEDIA or E.DOOROPEN, it must not return either value until it 
determines there is new media in the drive, or the drive door has been 
opened again. 


The SELECT function should only report ELNEWMEDIA or ELDOOROPEN 
if the condition arises while executing the select code. If either the 
E NEWMEDIA or ELDOOROPEN error is returned from a SELECT call, the 
Disk Resource Manager attempts one more SELECT call before 
reporting ELMEDIACHANGE to the user. 


6.2 Media Timed Verification (MTV) 


The Disk Resource Manager supports media timed verification (MTV) 
to increase the performance of removable media. Media timed 
verification relies on the fact that it takes some minimum amount of 
time for a user to remove the media and replace it with new media. 
Using this knowledge, the Disk Resource Manager can verify the media 
every N seconds (provided N is less than the minimum) and not miss a 
media change. The media is not verified when it is not in use, but is 
checked only during caching or I/O operations on the given media. 


Media timed verification is most useful on removeable media only 
(RMO) units where the Disk Resource Manager incurs considerable 
overhead verifying the media has not changed. Media timed 
verification can be useful on units that implement door open detection 
if executing the driver's DOD code takes excessive time. Media timed 
verification is of no use on units that use door open interrupts 
because there is no overhead for the Disk Resource Manager to check 
the door open flag. : 


6.3 Driver support for MTV 
Driver support for media timed verification is provided through the 
Disk Driver GET parameter block (see page 8-45 in the System Guide). 


Beginning with release 1.42, this parameter block is modified as 
follows: 
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@® an additional bit (bit 4) is defined in the dtype field. Bit 4 must 
be set to 1 (on) to enable media timed verification; otherwise it is 
disabled. 


® the ULONG value dvrdelta is added to the end of the parameter 
block. The dvrdelta field contains the number of milliseconds the 
Disk Resource Manager waits before performing a media check. 


When calling GET on a unit that supports media timed verification, the 
driver must set both bit 4 in the dtype field and the number of 
miliseconds for dvrdelta. 


Note: The Disk Resource Manager does a media check only when the 
media has not been accessed in the time span given by dvrdelta, but 
otherwise performs no check. 


End of Section 6 
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The SYSTAB Utility 


FlexOS contains a new utility named SYSTAB that displays the current 
status of the following system tables described in Section 8 of the 
FlexOS Programmer's Guide: 


CONSOLE 
DEVICE 
ENVIRON 
MEMORY 
PIPE 
PROCDEF 
PROCESS 
SHMEM 
SYSDEF 


SYSTEM 
VCONSOLE 


To use SYSTAB, enter the command: 
C>SYSTAB 


which displays the main menu of available commands and _ the 
command-line parameters that control the display operation. 


End of Section 7 


SECTION 8 


RNET Serial Driver 


RNETHSD.DVR is a high-speed serial device driver provided in 
executable form with the Programmer's Toolkit, and in both executable 
and source form with the System Builder’s Kit. The RNETHSD.DRV 
source code is fully commented, and illustrates the basic structuring of 
a device driver into synchronous and asynchronous portions. 


RNETHSD.DVR is the driver for the ARNET Multiport'™ Board, which is 
an RS-232 serial communications board designed for use with IBM AT 
and compatibles. 


If you need high-speed serial communications, you can use 
RNETHSD.DRV as an replacement for the standard serial driver 
SDRV.DRV. To do this, you edit the source code, setting the 
conditional compilation switch, then recompile to make RNETHSD.DRV 
communicate directly with the hardware ports COM1 and COM2. In its 
defauit configuration, RNETHSD. ORV communicates with the ARNET 
board (see figure on the following page). 

Note: Normally, the serial driver SDRV.DRV communicates with the 
port driver PTO:, which then communicates directly with the hardware 
ports. If you use RNET.DRV, it communicates directly with the 
hardware ports and overrides the port driver, thus disabling the 
capability of using a serial terminal or a mouse. 


RNET Serial Driver 


(Serial Driver (SORV.DRY)|| 


[Port Driver (PTO| 
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|ARNET Driver (RNET.DRV) | 


[Hardware Ports (COM1, COM2)|-------| |RNET Board| 
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End of Section 8 


SECTION 9 


Limits on Processes 


The Intel 286 microprocessor architecture imposes on FlexOS certain 
limits on system values such as the number of files that can be 
opened, the maximum number of concurrently scheduled ASR’‘s, and 
the size of internal memory pools. These values. are all configurable 
by editing the system files CONFIG.C, CONFIG.H, and ACONFAT.A86. 


If you encounter problems because these numbers are too small, 
simply edit the system configuration files and increase the values. For 
example, you can increase the size of the internal memory pools, or 
the number of entries for the File Number Table, then recompile and 
relink the system. 


Also, adhering to the following guidelines may help you avoid 
problems related to the limitations imposed by these default values: 


@® Use the HSET command (see the Programmer's Utilities Guide, 
Appendix L) on all executable files to set the code group 
Descriptor in the .286 file header to 09 (shared code). 


@ Conserve space in the File Number Table by closing all unused 
files =numbers, including the Standard’ file numbers 
— (stdin,stdout,stderr,stdcmd) associated with each process. 


End of Section 9 
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SECTION 10 


Documentation Errata 


This section contains corrections and/or additions to the indicated 
manuals. You should annotate your manuals accordingly. 


Ce ee ne eemneeepnmensiuamnmnnnaeean eanmna nnn emaxarnmesaeen nario 


FLEXOS'™ 286 PROGRAMMER’S UTILITIES GUIDE, (1073-2043-001) 


In Section 7, change all references to the .CMD filetype to .286 filetype. 
On page 7-18 at the bottom, change the sentence 


“LINK 86 makes multiple passes through the library index when 
attempting to resolve references from other modules.” 


to read as follows: 

"LINK 86 makes multiple passes through the library index when 
attempting to resolve references from other modules within the 
library.” : 


On page 10-5 in the explanation of the fourth example, change “12800 
bytes” to "128K bytes”. 


FLEXOS'™ SYSTEM GUIDE, First’ Edition. November 1986 


~ (1073-2013-001) 


In section 3.2 on page 3-3, change the reference in the fourth 
paragraph from FlexOS User's Guide to FlexOS Configuration Guide. 


In Listing 4-1 on page 4-2, change the line: 


UWORD dh_reserved ;/* Reserved /* 


to read as follows: 


UWORD dh_dtype 3/* Type of Driver T= 
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Also change the top line of Figure 4-2 on page 4-3 from: 


+----- +~--- He +—-—------- +-------- + 
0 | Reserved | Units | Flags | 
+—----- 7 +-- >a +o eee +—-------- + 
4 | INIT Function Entry Point | 
t------- +------- to oH HH t--- ee + 


to the following: 


O 1 2 3 
+-~------ +—--—----- +—-—------- +m nme + 
0 | Driver Type | Units | Flags | 
+------- +~-—-—---- +—-—--—----— +—-~~------ + 
4 | INIT Function Entry Point | 
4—------- +------- +—-—------- +—------+- —+ 


and add the following explanation to Table 4-1 on page 4-4: 


Driver Type A word-length description of the type of the driver 
as listed in Table 4-3. 


Add the following to the explanation of the fields in Table 4-2, “Driver 
Header Synchronization Flags” at the bottom of page 4-6: 


Flag bit 4 controls delimited reads. Set bit 4 to zero to use the 
delimited read routine supplied by the Console Resource Manager. 
On systems that do not have a Disk Resource or Console 
Resource Manager, set bit 4 to one to have a user-supplied driver 
perform the delimited read. 


On page 4-10, add the following entry to Table 4-3: 


75 Mouse Driver 
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On page 4-11, make the following changes to Table 4-4: 


@ Add bit 10 as follows: 


Bit 10: 0 = Install subdriver 
| 1 Uninstall subdriver 


@® Change “Bits 10-12” to “Bits 11-12”. 


In Figure A-1 on page A-2, note that the state bits (8-11) do not 
apply to the Toggle characters. 


The figure on page A-3 is incorrect. It should be identical to the 
figure on page A-11 of the Programmer's Guide: 


bit: 15 14 13 12 11 10 9 8 7 0 
:sliedieaticediadin diemaiantieadicatis sieetiatentieate aiteatieateatnadth ateetadeatiatn steatieatinedtantn sieateteattetn steadied ake a —-—--—+ 
! 3 (A! key 
tame be mm te ee tH eH te HH tH HH HH eH tH HH tH + —--~--+ 
FLEXOS’™ USER GUIDE, Second Edition: August 1987 (1073 2004 002) 


On page 1-1, change the paragraph: 


"An option lets you modify what a command does. Multiple options 
are separated from each other by hyphens (-).” 


to read as follows: 


An option lets you modify what a command does. Multiple options 
are separated from each other by hyphens (-). The hyphen is the 
default switchar, or options separator (see Table 1-6). The switchar 
must be a single character; it cannot be any of the following: 


/ (backslash) , (comma) ; (semicolon) = (equal sign) 
On page 1-10 in Section 1.8.4, change the example to read as follows: 
A>DEFINE PROMPT=Your wish is my command$g 


On page 3-2, change the example at the top of the page to read as 
follows: 
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‘If you are on drive B and you want to run CLEANUP.BAT from drive A, 
enter the command: | 
B>A: CLEANUP ee 
/ : 
CLEANUP.BAT runs its commands against the files on drive B. When it \ / 
is finished, tt leaves you in the root directory of drive B. 


On page 3-3, make the following changes: 


@ in the middle of the page change: 


DEL 4% 
DIR & 
DEL % 
DIR % 
to read: 


DIR @1 
DEL @1 
DIR $2 
DEL %2 
@ Ai the bottom of the page change: 


DEL %2 
DIR %2 
DEL %@1 
DIR 31 


to read: 


DIR 
DEL 
DIR 
DEL 


On page 3-22, delete the sentence that reads: 


rH Fk NO NO 


XP oO a0 oO 


“VERIFY does this whether it is on or off.” 


a 
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FLEXOS'™ USER’S REFERENCE GUIDE, First Edition: August 1987 
(1073-2064-001) 


On page 1-20, change all references of SHELL.EXE to SHELL.286. 
On page 1-26, change the example 

A>COPY B:MYFILE 
to read as follows: 


A>COPY B:MYFILE.TXT 


On page 1-43, make the following changes: 


- @ In the first paragraph under Examples delete the sentence that 
reads: 


"FlexOS waits for you to enter another command”. 


@ Change the example at the bottom of the page to read as follows: 


QIAN ATT 
BMomMyy vee 


TIME -D 

ECHO Although ECHO is OFF, this message 
ECHO is displayed. | 

REM This line will not be displayed. 

ECHO ON 

REM When ECHO is ON, remarks are displayed 
REM as well. 


On page 1-51, delete the sentence at the bottom of the page: 
“Items in a FOR command line must be filenames.” 


On page 1-53 and 1-54, disregard any references to physically 
formatting the hard disk. You should always assume that a hard disk 
has been- physically formatted by the manufacturer. The 
documentation regarding logically formatting a hard disk is correct. 


On page 1-67 in the explanation of the example, change references to 
“noname” to “No-Name”. : 
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On page 1-92 in the Explanation, change the sentence: 


‘lf you do not specify a path for the source drive, the files are 
restored to the current directory.” i & 


to read as follows: | 7 YS 


“If you do not specify a path for the source drive, files backed up from 
the current directory are restored to the current directory.” 


On page 1-101 make the following changes: 
@® Change the example command line: 
A>SORT < PARTTIME.LST >> FULLTIME.LST >PRN 

to read as follows: 
- A>SORT < PARTTIME.LST >> FULLTIME.LST 

@ Delete the sentence: 
“This file is redirected to the printer device PRN:.” 

@ On page 1-109, delete the sentence that reads: 


"VERIFY does this whether it is on or off.” 


End of Section 10 


a2. 


ne | 


AS 
AF 
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Change Pages 


The pages following this one are change pages for the Programmer's 


Uitiltes Guide, (1073-2043-0071). 


Replace all the pages in Appendix B and Appendix H. 
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Appendix B 


Creating Shared Runtime Libraries 


B.1 Shareable Runtime Libraries 


This appendix describes the procedures for creating and modifying 
shareable runtime libraries (SRTLs). SRTLs allow multiple users to 
share a single copy of library code at runtime. This makes it 
unnecessary for each user to store library code in a command file. 
When libraries are shared, only references to the library code are 
linked with the user’s object files. 


Before attempting to create or modify shareable runtime libraries, you 
should be familiar with the 80286 architecture, memory models, and 
calling conventions. You should also be familiar with conventions 
used when writing reentrant code. 


You can write most shareable runtime library code in C, or most other 
high level languages. The only code that cannot be written in a high 
level language is the transfer vector code, which handles the calls 
from the user program to the SRTL routines. Transfer vector code 
must be written in 80286 assembly language. 


See Section 7 in this manual for a description on how to link 
shareable runtime libraries with your object files. | 


B.2 SRTL Components 
A SRTL consists of two types of files: 


@® A shareable runtime library file which contains the basic shareable 
Object code created by LIB-86. The filetype is .L86. 


@ An XSRTL code file which contains an executable version of the 
SRTL created by LINK 86. The filetype is .SRL. . 


_ This appendix describes how to create these two files. 


B.3 Creating a SRTL Programmer's Utilities Guide 


B.3 Creating a SRTL 
Creating a SRTL involves the following general steps: 


1. lf you plan to compile the SRTL using a Large memory model!, 
you must modify the source of the library routines to use the 
proper calling conventions. 


2. Create the transfer vectors. 


3. Compile the source for the library routines and transfer vectors to 
_ create object modules. 


4. Create the LIBATTR module. 
5. Use LIB-86 to create the SRTL. 
6. Use LINK 86 to create an executable SRTL (XSRTL). 


These steps are described in detail in the following sections. 


B.3.1 Modifying the Source 


To create a C language SRTL (in Large memory model) with the ~ 
recommended transfer vectors, you must modify the SRITL library 


source code. Two modifications are required: 


1. The formal parameter lists of the entry point routines in the SRTL 
must include three extra words of parameters. These parameters 
provide “placeholders” for the extra information inserted onto Pane 
stack by the transfer vector (see Section B.3.2). 


2. Any intra-library calls to the entry point routines must have three 
words added to the actual parameter list, preceding the “real” 
parameters, so local calls emulate the stack activity of external 
calls through the transfer vectors. External calls must call the 
transfer vector symbol name, but are otherwise unchanged. 


'The type of memory model you use is dependent on your compiler. As used here, 


Large refers to a memory model that allocates multiple code, data, and heap segments, 
as well as a separate segment for the stack. 
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If transfer vectors are used, intermediate names must be put in 

the library. This is also true for Small memory model* SRTLs 

using a transfer vector at the beginning of the library in order to 
( make all entry points constant. 


Using C conditional compilation statements, a single set of sources 
could be used for both shareable and nonshareable libraries, as shown 


below: 
#ifdef NonShareable - 
strcpy (to, from) 
char *to, *from; 
#else 
strcpy (d1, d2, d3, to, from) 
WORD dl, d2, d3; 
char *to, *from; 
fendif 
#ifdef NonShareable 
strcpy (source, target); 
#else 
strcpy (0, 0, O, source, target); 
#endif 
( 


As used here, Small refers to a memory model that allocates a single segment for the 
program’s data, heap, and stack. 
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B.3.2 Creating the Transfer Vectors 


There are many possible transfer vector calling conventions for 
handling calls between user programs and _ SRTLs. The calling 
conventions you use depend on your application and your 
programming style. However, the transfer vector calling conventions 
described here are the only ones tested and supported by Digital 
Research. 


There are two types of transfer vectors: User and SRTL. 


User Transfer Vector 


lf the user program uses a Large memory model SRTL, calls to the 


SRTL routines must first pass through a transfer vector. This transfer 
vector, referred to as a User Transfer Vector, stores the value of the 
user program's DS register and loads the SRTL’s DS register prior to 
entering the SRTL. Upon exiting the SRTL, the transfer vector restores 
the user program’s DS register. The user transfer vector must reside 


in the user program's code space and must have a separate entry for 


each entry point into the SRTL. 


See Section B.5 for more information on User Transfer Vectors. 


SRTL Transfer Vector 


If either memory model is being used, you can create an optional SRTL 
Transfer Vector that resides in the SRTL. This transfer vector is a 
collection of jumps that establish the SRTL entry points at fixed 
locations. By making an entry point into the SRTL a fixed location 
(constant virtual address), user programs do not have to be relinked 
each time a change is made to the library. 


There must be an entry in the SRTL Transfer Vector for each entry 
point into the SRTL. 


Note: To make SRTL entry points constant, any object modules 
containing the SRTL transfer vector must appear immediately after the 
LIBATTR module in the SRTL. 
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B.3.3 Creating the Object Modules 


This step involves compiling the library source files to create library 


-. Object files. Be sure to set any compiler options required to generate 


the object files using the correct memory model. 


B.3.4 Creating the LIBATTR Module 


Each SRTL is associated with a specific set of attributes. These 
attributes include: 


@ the SRTL’s name 

@® the SRTL’s version number 

@® the SRTL’s data location when using the Small memory model 
® whether the SRTL is shared or not shared by default 


The attributes of a SRTL are established by including a module with 
the name “LIBATTR” in the SRTL library file. 


Note: The LIBATTR module must be specified as the first module in 
the list. 


The LIBATTR module should contain only a single data segment with 
name “LIBATTR”. The contents of this segment must have the format 
indicated by the lib id and lib attr structures shown in the listing 
below. The equivalent form in RASM-86 code appears in the example 
at the end of this appendix. 


struct lib_id { 


char }i_ name([8]; 
unsigned short li ver_major; 
unsigned short }i ver minor; 


unsigned char 1i_ flags[4]; 
ys | 
struct lib attr ( 


lib id la_id; 
unsigned short la _data_offset; 
char la_share attr; 
); 
#define LA_S SHARED Ox) 
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Li B ID Structure 


The lib id structure defines the fields used to identify the SRTL 
including its name, version numbers and flags. The lib id fields are: 


li name 


li ver major 


li ver minor 


li flags 


This is the physical name of the XSRTL specified by 
users of the SRTL. If this field is nonblank, the 
library is a SRTL; otherwise the library is a normal 
library. This field must be exactly 8 bytes long, 
including trailing blanks. | 


This is the major version number. It should be 
updated when there are major changes to a library 
that make it incompatible with previous versions. 
The FlexOS program loader verifies that the major 
version number specified in a user program is 
identical to that of the XSRTL. 


This is the minor version number. It should be 
updated when changes to the library do not create 
incompatibilities with previous versions. The minor 


version number specified in a user program does 


not have to exactly match that specified in the 
XSRTL. 


This field contains flags that distinguish different 
variants of the library from one another. Currently, 
only the low-order 6 bits of li flags[3] have been 
assigned the following values: 
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LiF CMD (0x0) 


Li F 286 (0x1) 
LIF EXE (0x2) 
(0x3 through OxF) 


LIF DUP_MAIN (0x10) 


LI F DS STACK (0x20) 


This flag informs LINK 86 the code file suffix 
should be CMD. If this, or any other value is 
specified to a version of LINK 86 that cannot 
generate that style of code file, an error is 
generated. For example, the LINK 86 version 
that generates CMD and 286 files cannot 
generate an EXE file and vice versa. 


This flag informs LINK 86 the code file suffix 
should be 286. 


This flag informs LINK 86 the code file suffix 
should be EXE. 


These values are unassigned and cause an 
error if specified in a LIBATTR module. 


This value informs LINK 86 that duplicate 
definitions of the symbol “main” are permitted 
and should not generate errors. 


This value informs LINK 86 the stack appears at 
the low end of the data segment. When this 
bit is set, the value of the data offset field 
represents the size of this stack. If multiple 
LIBATTR modules are found, the smallest 
data offset value is used. Data is allocated 
above the stack and the public variable ?STACK, 
if present, is initialized to the size of the stack. 
The variable ?STACK is assumed to be allocated 
a word (2 bytes). 
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LIB ATTR Structure 


The fields in the lib attr structure determine the SRTL’s memory offset, 
and whether or not the SRTL is shareable. The lib attr fields are: 


la id This field specifies the library id. 


la data offset With the Small memory model, this field contains 
the fixed address where the SRTL data must appear. 
This value is also used to prevent LINK 86 from 
allocating user data at the same location as the 
SRTL data. With the Large memory model, this field 
must have the value OxFFFF. 


LA SHARE ATTR_ This field tells LINK 86 whether the library by default 
is shared (value 1) or not shared (value Q), so you 
do not have to specify the SHARED option every 
time the library is used. You can override this 
default as specified in Section 7.5. 


When linking a user program, LINK 86 determines that a library is a 
SRTL by checking the name of the first module in a library. If the first | 
module has the name “LIBATTR”, LINK 86 examines the contents of the ~ 
LIBATTR segment to determine the attributes of the library. Depending 
on the value of the LA SHARE ATTR field and input options, the library 
is treated either as a SRTL or as a regular library. 


Before creating a LIBATTR module, you must determine the filename of 
the executable shareable runtime library (see Section B.3.6) and the 
data offset if the Small memory model is used. You must also ensure 
the sizes and offsets of data items correspond to the fields in the 
LIBATTR definition given above. The LIBATTR segment must contain 
exactly 19 bytes. 


When linking your file(s) with a SRTL, do not include the LIBATTR 
module in your user code file. The LIBATTR module is used only to 
define the attributes of the SRTL and should not be treated as a 
normal module. The LIBATTR module is included in the code file only 
when the SRIL is linked aS a normal, nonshared library (without ( 
specifying the SEARCH option). Ree 


Se 
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B.3.5 Creating the SRTL 


You create a SRTL using LIB-86. When entering the command line, 


you must specify the LIBATTR object file as the first file in the library. 


If the optional SRTL Transfer Vector is used, it must be the second 
Object file in the library. 


For example, to create a SRTL named SMISRITL using the LIBATTR file, 
LIBATTR.OBJ, and the object files: TVECT.OBJ, SVCIF.OBJ, and 
RTESRTL.OBJ enter the command: 


1ib86 smisrt!l.186([map,xref |=libattr.obj,tvect.obj,svcif.obj,rtesrtl.obj 


Assuming all calling conventions are correct, you can modify an 
existing nonshareable runtime library to create a shareable library by 
including a LIBATTR file in the LIB86 command. For example, to make 
the nonshareable library OLDLIB.L86 into the shareable library NEWLIB 
using a LIBATTR file named LIBATTR.OBJ, enter: 


1in86 newlib = libattr.obj, oldlib.186 


B.3.6 Creating the XSRTL 


A library file cannot be loaded by the operating system and executed. 
Therefore, an executable version of the library file must be available. 
This version of a SRTL is called the XSRTL (eXecutable Shared Run 
Time Library). | | 


Once you create a SRTL, you then create the XSRTL by linking the 
SRTL, as shown in the following example. LINK 86 automatically 
recognizes the library is a SRTL by the presence of the LIBATTR 
module. 


The command: 
bink&BO smtlsrti.srl=smisrt!. 186 


creates a file SMISTRL.SRL, containing the executable version of the 
library file SMISRTLL86. With the exception of the LIBATTR module, 
LINK 86 processes all code and data from all modules in the library in 
the order they appear in the library. During the link process, the 
addresses of the data are resolved, but the data is not included in the 
XSRTL, which contains only the SRTL code. This convention is 
necessary to ensure that the references in a SRTL user program match 
the XSRTL, since both are linked separately. 
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The XSRTL has no main program, but this is not a problem, because 
LINK 86 knows it is an XSRTL. Also, the XSRTL cannot contain any 
unresolved external references, because there is no way to resolve 
them separately to each of multiple, simultaneous user programs. 


Note that the value of the data offset attribute from the LIBATTR 
module determines whether the XSRTL uses the Small or Large 
memory model. If the attribute value is OxFFFF, the Large memory 
model is assumed. Any other value indicates the offset of the SRTL 
data within the data segment, which means the XSRTL uses the Small 
memory model. 


B.4 Small & Medium Model SRTLs 


When creating a SRITL for use with the Small or Medium Memory 
Model, you must decide beforehand where the SRTL data appears and 
code this as the value of the data offset attribute in the LIBATTR 
module. The location DS:0 is not acceptable, because the stack 
overflow detection requires the stack to be at the bottom of the data 
segment. On the other hand, putting the SRTL data at the top of the 
data segment does not efficiently utilize memory. The layout of the 
data segment for a Small memory model program should resemble 
that specified in Figure B-1. 


+—---~---~-------- + 
| SRTL Data | 
+—--—------~------- + 
| Stack | 
| | 
| | 
| ; | 

DS:0 SS SSS SS Se + 


Figure B-1. Small Memory Model Data Segment 


er SS 
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If the size of the stack exceeds the starting address of the SRIL data, 
LINK 86 prints an error message and terminates the link. 


B41 Calling Conventions 


A file compiled using the Small memory model must be linked with a 
Small model SRTL so that both the user file and the SRTL can agree 
on the location of the SRTL data. This restriction fixes the calling 
convention as illustrated in Figure B-2 below. 


() S & R S$ R TL 
Calling Sequence Transfer Vector Transfer Vector C Prologue/Epilogue 
X() | Ke UIMPR OX” seeeeee So -R0as IMPE C Se eeeee Se eC) 


ae ( 


C code 


+ —e—er—se er rw" — 


Figure B-2. Small Memory Model Calling Convention 


The calling convention shown in Figure B-2 uses a SRITL Transfer 
Vector. If no SRTL Transfer Vector is used, the reference to the SRTL 
routine would go directly to the SRTL instruction, rather than the JMPF 
instruction in the transfer vector. 


Note that the SRTL code sequence in Figure B-2 can have one or more 
code segments and, therefore, can be used with the standard Medium 
memory model consisting of multiple code segments and a single data 
segment. 


B.5 Large Model SRTLs 


B.5 Large Model SRTLs 


To have reentrant code, the SRTL data 


rather than the SRTL. When using the Large memory model, the user 
location of 


file must inform the SRTL of the 
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must belong to the user file, 


—— aS 


its data. AS a 


consequence, user calls to Large memory model SRTL routines must 
pass through a User Transfer Vector, as described in Section B.3.2. 


B.5.1 Calling Conventions 


The SRTL determines the location of the 


user file’s data by mapping all 


references to the SRTL through a transfer vector local to the user. 


The transfer vector pushes the user’s 
before calling the SRTL routine, then po 


DS and loads the SRTL DS 
ps the user’s DS after control 


returns from the library. This convention is shown in Figure B-3. 


US ER 


Calling Sequence Transfer Vector 


SS PUSH DS 

MOV AX,SRTLDS 
| MOV DS,AX 

| CALLF Xx’ 


eee eee ete wee 
ee erectile titeesatiimsetie tiem 


Figure B-3. 
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Large Memory Model Calling Convention 


Note that this calling convention assumes the creator of the library 


coded a transfer vector containing the 


this were not the case, the CALLF in the user’s transfer vector would 
directly reference the instruction in the SRTL routine. 
vector on the SRTL side, though not necessary, is recommended. 


entry points to the library. If 


The transfer‘ 
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B.6 SRTL Restrictions 
When creating SRTLs, keep the following restrictions in mind: 


@® XSRTLsS cannot contain any unresolved external references. 
@® XSRILs cannot contain overlays. 


@ A SRTL can contain a maximum of 255 object modules, not 
counting the LIBATTR module. 


B.7 Example SRTL 


The following C code tests a Small memory model SRITL by calling the 
SRTL subroutine LIST PRINT twice. 


[EERE E EKER KKK KKK KKK ROKR RK ROR OK KOR KKK KKK eR KK OK KKK KK OK OK OK OK OK 


+ Main program to call a Shared Run Time Library (SRTL) * 
AO ARR OR ROR OR OTOR ORO RR ROO TOR ROKR OR KOR ROKK / 


extern far void list print( far char *  ); 


void main() 

{ 
list print ( far char *)"\n\r\tIn Main first time : “ ); 
list print( ( far char *#)"N\o\eNtIn Main second time: “ ); 


The C code on the following page defines the LIBATTR (Library 
Attribute) module. The LIBATTR module defines the attributes used by 
LINK 86 when linking XSRTLsS (eXecutable SRTLS) and when linking to 
Other SRTLs. The LIBATTR module must appear as the first module in 
a SRTL. 
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Y fs Tooateneieeenentceneententatentieiententantentantentantentantaetantatmediontnatantantantantenentcntentemtantantatamtentantententadentmetnententententententantmtentnmtatantiaatmatentententantaatoen * 
* LIBATTR.C -- The library attribute module for a SRTL : 
Kn ee ee ee ee ee * / 


typedef struct 


{ 
char 1i_name[8]; 
unsigned short 1i_ver_major; 
unsigned short li ver_minor; 
unsigned char li _flags[{4]; 
} lib_id; 


typedef struct 


{ 
lib id la_id; 
unsigned short la_data_offset; 
char la_share_ attr; 


} lib_attr; 


static lib attr attrib = 


{ 

{ LE SaaS Lib _id structure —-~~--~---- is 
"“SMISRTL ", /* li name[8] zi 
0x9876, /* }i_ver_major * / 
0x5432, ff }i_ver_minor ey 
{ 0,0,0,0x31 } /* Ji _flags[4] * / 

I [RSS eee See eee eee 7 

0x0400, /* la data_offset : * / 

/* OxFFFF for large model oy 
01 /* Shared attribute ae A 
5 
[¥ anes aaa asa n ee ee ee sa eeeess= End of LIBATTR.C------------~----------- */ 


The C code on the following page defines SRTL routines that test 
Small memory model SRTLs. The LIST PRINT routine loads the string 
into the variable | and calls the CONSOLE PRINT, which prints the 
string on the console. 


Programmer's Utilities Guide B.7 Example SRTL 


/* 
* ‘C’ Shared Run Time Library routines 
+ / 

Finclude "“flextatb hh" 


[AHH HOH OR OOK RRR OK OK OR ROKK RK EOF 


* _FItl CHAR is a MetaWare intrinsic function * 
DARPA RPO eee eee eee eee eee ee eee eee cee ee eee ee eee ee ee, 


Fdef ine blkfil!l(where,what,how many ) _fill_ char(where,how many,what ) 
Fdetine ZERO PARMS bIikfill (&pblock,NULL,sizeof (pblock) ) 


extern long  sveif(); 
far void  Jlistprint( far char * ); 


long Console print ( far char * ); 
_t es 


[ROA OO IR RIOR OR IORI RIOR RRO IO ORK KOR ROK KOK 


* _LISTPRINT * 
* This is the entry into the Shared Run Time Library for the * 
+ sample program TEST.C * 


ROR OR HORROR ROR ORR HORI ORO ROOK ORO OIRO RK KK / 


far void Jlistpeint( far char *i ) 


console orintt ( far char *)"\n\rNow in the SRTL XxX i sre 
console print( i); 
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[ER KEK KR ERE EKER KKK KK KEK KKK EEE KER KEKE RKEKE KEE KKK KKH KKK KKK KKK KKK EK KKK KOK K€ 


* CONSOLE PRINT ok 
* This is the same as a runtime library call to the S_ WRITE * 
* function. We must use it here because we can not use any * 
* external references outside of our Shared Run Time Library. * ye 


KKK KKK EEE REE KK EK KEKE KK EERE KER ERK E KKK EK ERE KEE KEK KKK KKK KKK EEK KR KKK KK KK / ‘ 


long console print( (far char *buffer ) 


( 
struct PARAMBLOCK pblock; 
ZERO PARMS; /* zero-init entire parm block */ 
pblock. pflags = 0; ; 
pblock. pparaml! = IL; /* Fnum for STDOUT bal 4 
pblock. pparam2. pp2long = (LONG)buffer ; 
pblock. pparam3 = 24L; /* Length of the Write. */ 
pblock. pparam4 = OL; 
return( _=svcif( F_WRITE, ( far BYTE *)&pblock ) ); 

} 

[ PABA S eS eee See eae eS SSeS Ss End: of RIESRI LL. Clee See 2 se3S > See 3 ee s5 * / 


End of Appendix B | ee a 
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LINK 86 Error Messages 


During the course of operation, LINK 86 can display error messages. 
The error messages and a brief explanation of their cause are listed 
below. The number in parenthesis following the error message is the 
system return code. This number can be used with the IF command in 
a batch file to determine if an error condition is true of false. 


Table H-1. LINK 86 Error Messages 


Message Meaning 


— 


NO BLOCK OR DIRECTORY ENTRIES AVAILABLE (01) 
There is no more space available on the disk for 
data or directory entries. 


8087 IN OVERLAY, NOT IN ROOT (02) 
The 8087 emulator, if used, must be referenced in 
the root if it is to be referenced in an overlay. 


8087 SWITCH OCCURRED AFTER FIRST FILENAME (03) 
The HARD8087, AUTO8087, and SIM8087 switches 
must not appear after the first object file listed on 
the command line. 


8087 TABLE OVERFLOW (04) 
The 8087 fixup table needed with the AUTO8087 or | 
SIM8087 options can have a maximum size of 64K. 


ALIGN TYPE NOT IMPLEMENTED (05) 
The object file contains a segment align type not 
implemented in LINK 86. 


H LINK 86 Error Messages | Programmer's Utilities Guide 


Table H-1. (continued) 


Message Meaning 


CANNOT CLOSE (06) 
LINK 86 cannot close an output file. Check to see if 
the correct disk is in the drive and the disk is not 
write-protected or full. 


CLASS NOT FOUND (07) | 
The class name specified in the command line does 
not appear in any of the files linked. 


COMBINE TYPE NOT IMPLEMENTED (08) 
The object file contains a ecaeeer alan type not 
implemented in LINK 86. 


COMMAND TOO LONG (09) 
The total length of input to LINK 86, including the 
input file, cannot exceed 2048 characters. 


DISK READ ERROR (11) | 
LINK 86 cannot properly read a source or object file. 
This is usually the result of an unexpected end-of- 
file character. Correct the problem in your source 
file. 


DISK WRITE ERROR (12) | 
A file cannot be written properly; the disk is 
probably full. | 


ERROR IN LIBATTR MODULE (13) 
The LIBATTR module does not conform to 
established requirements. Fix the LIBATTR module 
and rebuild the library in question. 


a 
. 
* a x 
| 
NC v 
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Table H-1. (continued) 


Message Meaning 


FIXUP TYPE NOT IMPLEMENTED (14) 
The object file uses a fixup type not implemented in 
LINK 86. Make sure the object file has not been 
corrupted. 


GROUP NOT FOUND (15) 
The group name specified in the command line does 
not appear in any of the files linked. 


GROUP OVER 64K (16) 
The group listed must be made smaller than 64k 
before relinking. Either delete segments from the 
group, split it up into 2 or more groups or do not 
use groups. 


LINK 86 only supports segments as elements of a 
group. 

INVALID LIBRARY-REQUESTED SUFFIX (18) 
The command file suffix requested by a library is 
not supported. Verify that the correct library is 
being used. 

LINK-86 ERROR 1 (19) 


This error indicates an inconsistency in the LINK 86 
internal tables, and should never be emitted. 


MULTIPLE DEFINITION (20) 
The indicated symbol is defined as PUBLIC in more 
than one module. Correct the problem in the 
source file, and try again. 

MORE THAN ONE MAIN PROGRAM (21) 


A program linked by LINK 86 may have at most one 
main program. 


7 cena nnn eat wwe steerer ateennannemtetaetit 
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Table H-1. (continued) 


Message Meaning 


NO FILE (22) LINK 86 cannot find the indicated source or object 
| | file on the indicated drive. 


OBJECT FILE ERROR (23) 
LINK 86 detected an error in the object file. This is 
caused by a translator error or by a bad disk file. 
Try regenerating the file. 


RECORD TYPE NOT IMPLEMENTED (24) 
The object file contains a record type _ not 
implemented in LINK 86. Make sure the object file 
‘has not been corrupted by aspenelenne it and 
linking again. 


SEGMENT OVER 64K (25) 
The segment listed after the error message has a 
total length greater than 64k bytes. Make the 
segment smaller, or do not combine it with other 
PUBLIC segments of the same name. 


STACK COLLIDES WITH SRTL DATA (26) 
The base address of SRTL data does not allow 
enough room for the requested amount of stack 
space. Change the base of the SRTL data in the 
LIBATTR module or request less stack. 


SRTL DATA OVERLAP (27) 


The data from 2 SRTLs overlap. Change the base 
address in the LIBATTR module of one of the SRTLs. 


SRTL CANNOT CONTAIN 8087 FIXUPS (28) 


A SRTL cannot use the 8087 emulator as currently 
implemented. 


q 
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Table H-1. (continued) 


Message Meaning 


SEGMENT CLASS ERROR (29) 
The class of a segment must be CODE, DATA, 
STACK, EXTRA, X1, X2, X3, or X4. 


SEGMENT ATTRIBUTE ERROR (30) | | 
The Combine type of the indicated segment is not 
the same as the type of the segment in a previously 
linked file. Regenerate the object file after changing 
the segment attributes as needed. 


SEGMENT COMBINATION ERROR (31) 
An attempt is made to combine segments that 
cannot be combined, such as LOCAL segments. 
Change the segment attributes and relink. 


SEGMENT NOT FOUND (32) 
The segment name specified in the command line 
does not appear in any of the files linked. 


SYMBOL TABLE OVERFLOW (33) 
LINK 86 ran out of Symbol Table space. Either 
reduce the number or length of symbols in the 
program, or relink on a system with more memory. 


SYNTAX ERROR (34) | 
LINK 86 detected a syntax error in the command 
line; the error is probably an improper filename or 
an invalid command option. LINK 86 echoes the 
command line up to the point where it found the 
error. Retype the command line or edit the INP file. 


TARGET OUT OF RANGE (35) 
The target of a fixup cannot be reached from the 
location of the fixup. 


ce ee ant te ane ree eee tains aR mit eT Ren a RNR INe ApS: = — nA en ROKR WIRES am icebmtr set 9% RR CREATE Wine ersten 
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Table H-1. (continued) 


Message Meaning 


TOO MANY MODULES IN LIBRARY (36) 
A library cannot contain more than 512 modules. 
Split the library into 2 or more libraries and relink. 


TOO MANY MODULES LINKED FROM LIBRARY (37) 
A library cannot supply more than 512 modules 
during the linkage process. Split the library into 2 
or more smaller libraries and relink. 

UNDEFINED SYMBOLS (38) 


The symbols following this message are referenced 
but not defined in any of the modules being linked. 


XSRTL MUST BE LINKED BY ITSELF (40) | 
When linking an XSRTL, no other files may be linked 
at the same time. | 7 


XSRTLs INCOMPATIBLE WITH OVERLAYS (41) 
An XSRTL cannot use overlays. 
OBJECT FILE OVER 64K (42) 
The object file created by LINK 86 is greater than 
64k. Break the code into modules and relink. 
TOO MANY MODULE NAMES (43) 


There are too many library module names. Combine 
modules and relink. | 


End of Appendix H 
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1.2 Supervisor Calls 


Table 1-2. (Continued) 


Call 


Action 


Real Time and Process Management 


TIMER* Set and wait for timer interrupt 
ABORT* Abort specified process 
COMMAND* Perform command 

EXCEPTION Set software interrupts on exceptions 
MALLOC Allocate memory to heap 

MFREE Free memory from heap 

EXIT Terminate with return code 
ENABLE Enable software interrupts 
DISABLE Disable software interrupts 
SWIRET Return from software interrupt 
CONTROL* Control a process for debugging 
OVERLAY Load overlay from command file 


Device Management 


SPECIAL” Perform special device function 
DEVLOCK Lock or unlock device for user/group 
INSTALL Install, replace and associate drivers 


Table Management 


GET Get a table 
SET Set table values 
LOOKUP Scan and retrieve tables 


“ Your program can call these SVCs asynchronously. 


Table 1-3 lists the SVCs by their number. 
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Table 1-3. Supervisor Calls by Number 


Number Call Number Call 
0 F_GET 2 1 Reserved 
1 F_SET 22 F_GIVE 
2 F_LOOKUP 23 F BWAIT 
3 F_CREATE 24 F_TIMER 
4 F_DELETE 25 F_EXIT 
5 F_OPEN 26 F_ABORT 
6 F_CLOSE 27 F_CANCEL 
7 F_READ 28 F_WAIT 
8 F_WRITE 29 F_STATUS 
9 F_SPECIAL 30 F_RETURN 
10 F RENAME 31 F_EXCEPTION 
11 F_DEFINE 32 F_ENABLE 
12 F_DEVLOCK 33 F_DISABLE © 
13 F_INSTALL 34 F_SWIRET 
14 F_LOCK 35 F_MALLOC 
15 F_COPY 36 F_MFREE 
16 F_ALTER 37 F_OVERLAY 
17 F_XLAT 38 F_COMMAND 
18 F RWAIT 39 F_CONTROL 
19 F_KCTRL —40 F_ GSX 
20 F_ORDER AT F_SEEK 


1.2.1 Calling Conventions 


FlexOS Supervisor calls are made by invoking the FlexOS entry point. 
The entry point takes two arguments and returns a value, as follows: 


Arguments: a SVC 16-bit number 
a parameter block pointer or value, 32-bit 


Return: a 32-bit value 
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RECT C Structu re 


The RECT data structure defines a rectangular region of a FRAME. The 
point of reference is the FRAME coordinates of the region’s upper 
lefthand corner. The region's width and height are specified within the 
data structure in terms of character rows and columns. The SVCs 
using the RECT structure specify which FRAME planes are included in 
the RECT. Figure 3-5 shows the RECT data structure diagram. The 
corresponding C structure is as follows: 


struct RECT 


1 


WORD row,col,nrow,ncol: 
/* Top left corner FRAME coordinates 
and RECT width and height*/ 


+------- +------- +------- +------- + 
QO ! ROW ; COL ! 
+—------- +—------- +------- +------- + 
4 ! NROW ; NCOL ! 
+—------- +—~--~---- +------- +------- + 


Figure 3-5. RECT Structure 


The RECT fields are defined as follows: 


@® row: The row coordinate relative to the FRAME of the rectangle’s 
upper lefthand corner (counting begins at row 0) 


® col: The column coordinate relative to the FRAME of the 
rectangle’s upper lefthand corner (counting begins at row 0) 


@® nrow: The number of rows (height) in the rectangle 


@ ncol: The number of columns (width) in the rectangle 
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3.2 Controlling the Console 


Console attributes such as screen and keyboard modes, cursor 
location, and the number of character rows and columns are contained | 
in the CONSOLE table. You manage the console screen on a FRAME | 
basis with the ALTER and COPY SVCs and on a character basis with 
the WRITE SVC. 


3.2.1 Console Attributes 


The CONSOLE table is your reference source for information regarding 
console attributes and conditions. Figure 3-6 illustrates the CONSOLE 
table data structure. To get or set your process’s CONSOLE table, use 
0 or 1 or the stdin and stdout file numbers from the SE HMIBOIN table as 
the GET or SET ID value 


0 1 2 3 
+—-—------- +—---—----- +—-------- +—-—-—--—---- + 
0 ! TAHEAD SMODE 
+—-—------- +—-------- +—-------- +—-—------ + 
4! KMODE CURROW ! 
+—-—------- +—-------- +—-—------- +—-------- + 
8 of. CURCOL ! NROWS ! 
+—-------- +—-------- +—-—------- +—-—-—--—---- + 
12 ! NCOLS ! VCNUM ! TYPE ! 
+—-—------- +—-------- +—-—------- +—-—-----—-- + 
16 ! ' 
| + CNAME + 
20 1 t 
+ +—-—------- +—-—-—-—----- + 
24 ! ' 
+—-—-------— +—-------- + 


Figure 3-6. CONSOLE Table 
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Opening the Mouse File 


The mouse is Opened by calling OPEN. In your OPEN call you specify 
the mouse name, the access privileges required, and the access mode. 
The mouse name is vexxx/mouse where xxx is a decimal number 
indicating the current virtual console number. Get the virtual console 
number from the VCNUM field in your standard input file’s CONSOLE 
table. (Call GET with an ID vaiue of O to retrieve stdin’ss CONSOLE 
table.) For example, if the VCNUM value is 3, your mouse name would 
be vc003/mouse. 


In your OPEN call, specify at least read access privilege. If you need to 
set the MOUSE table, request set access as well. For the access mode 
specify exclusive mode unless mouse access will be shared by 
multiple processes. In this case, specify shared, shared file pointer 
mode. Access is restricted to processes with the same family ID. 


Your application should close the mouse file when you are done, 
otherwise you cannot close or delete the virtual console. CLOSE flag 
bit 0 has no meaning with respect to the mouse and ‘is ignored. 


Using BWAIT 


Use the BWAIT SVC to monitor button state changes. BWAIT counts 
the number of times a specified mouse button condition occurs within 
a given time period. A button condition is defined by two criteria: 
buttons and their ON or OFF state. 


The BWAIT form is as follows: 


ret s bwait(clicks,fnum,mask,state) ; 


emask = e bwait(swi,clicks,fnum,mask,state) ; 


The fnum value is the file number returned when you OPEN the 
vcxxx/mouse file. The mask and state parameters are 32-bit values 
which define the mouse button condition. 


You select buttons for the mask value by their position on the mouse. 
The leftmost button is represented by the least significant bit in the 
mask; the next button to the left is represented by the next bit, and so 
forth. To select the button, set its corresponding mask bit. 
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You define whether the button selected is to be ON or OFF in the 
state value. The Console Resource Manager looks only at the state bits 
corresponding to the buttons selected in the mask. Set the bit for ON. 


As an example of the use of the mask and state fields, consider a |, : 
two-button mouse. You can have the following button conditions: 


1. The left button is pressed (ON) without concern for the state of 
any other buttons: mask = 1, state = 1. 


2. The left button is pressed while the right button is not: mask = 3, 
State = 1.. 
3. The right button is pressed while the left button is not: mask = 3, 


state = 2. 


4. The right button is pressed without concern for the state of any 
other buttons: mask = 2, state = 2. = 


5. If either buttons is pressed: mask = 3, state = 3. 


Use the clicks value to delimit the event by a specific number of 
incidences of the specified button condition. You can specify any | 
number of clicks between O and 255. Use a click value of 0 to” 


determine the mouse’s current condition. BWAIT returns with a value ~* 


of 0 when you specify O clicks and the mouse is in the condition 
defined in the mask and state. 


BWAIT counts button conditions for a limited time period--the CLICK 
time limit specified in the MOUSE table. If the time period expires 
before the BWAIT click count is reached, the event terminates. The 
Console Resource Manager starts the timer upon the first incidence of 
the condition. Consequently, the count returned is always at least one 
except as described above. BWAIT returns a LONG value containing 
the following: 


TE RR RD RN SIRE TD SEES em Conny eet MEE SEE ime SERNIND GOED SEED 0 ED GED GENTE mS 0 ett eter eG EEE we ee 
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Using RWAIT 


RWAIT establishes an event boundary for the mouse. RWAIT returns 
with the row and column coordinates of the mouse’s hotspot when it 
crosses the boundary. The RWAIT form is as follows: 


position = s_ rwait(flags,fnum,region) ; 
emask = e rwait(swi,tlags,fnum,region) ; 


Set RWAIT flag bit 0 to clip the region to the current window borders. 
Otherwise, the region can include areas not visible on the parent 
screen. Flag bit 1 determines if the event occurs when the form exits 
or enters the region. Flag bit 2 allows the region rectangle to be 
defined as: COL,ROW,NCOLS,NROWS' instead of the default 
order:ROW,COL,NROWS,NCOLS. The other flag bits are not used. 


The region is a RECT structure confined to the calling process's virtual 
console’s FRAME. The position value returned is 32-bits where the 
high order word indicates the row and the low order word the column. 


3.4 Managing Virtual Consoles 


For applications with multiple processes sharing access to the console 
and keyboard, it is often necessary or convenient to have a separate 
virtual console for each process. The key to these applications is a 
process--the window manager--which creates the virtual consoles, 
sets each window's size and position, and passes keyboard and mouse 
access from one process to another according to a planned transfer 
scheme. (These are basically the same functions as the FlexOS window 
manager supplied with the operating system.) 


The window manager flow chart would include the following FlexOS 
functions; the SVCs used appear in parentheses. ) 


1. Create a virtual console (CREATE). 


. Get the virtual console number (GET). 


2 

3. Set the virtual console’s window size and location (SET). 

4. Assign the console file to stdin, stdout, and stderr (DEFINE). 
5 


. Define conditions under which keyboard and mouse ownership is 
returned (KCTRL and/or MCTRL). 
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6. Invoke shell or application that will use screen (asynchronous 
COMMAND). 


7. Give keyboard and mouse ownership to the new virtual console 
(GIVE). 


8. Read from your keyboard buffer (READ). 


9. Reorder the virtual consoles to put the selected one on top 
(ORDER). 


Steps 1 through 5 are repeated to create each virtual console. You 
have a numerical limit of 255 virtual consoles. 


3.4.1 Creating the Virtual Consoles and Windows 


To create a virtual console, you must specify the console screen on 
which it is to appear. This is called the parent screen. The virtual 
console created is referred to as a child console. Child consoles 
created on the same parent screen are referred to as sibling consoles. 
There are four rules of virtual console management based on these 
relationships: 7 


@ A child console always overlays its parent. 


® Sibling consoles are “stacked” on the parent in the order of their 
creation until reordered by ORDER. 


@ The ORDER SVC only reorders a “stack” of sibling virtual consoles 
and cannot be used to put a parent on top of a child. 


@® An application always has access to its entire console regardless 
of its virtual console’s position in the stack and the size of its 
window. 


Figure 3-9 illustrates the parent, child, and_ sibling console 
relationships and the three rules. As shown in this figure, you can 
have multiple tiers of virtual consoles. As you change tiers, the 
parent/child relationships change. All virtual consoles on a given level 
are siblings. 
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7.3 BWAIT | 


C interface: 


UWORD clicks; 
LONG mask; 
LONG state; 


ret = s_bwait(clicks,fnum,mask,state):; 
emask = e_bwait(swi,clicks,fnum,mask,state), 


ret = _osif(F_BWAIT,&parmbik); 


— parmbtk: 

+-—----~---- +-------- +-------- +-------- 
0 ! O=sync ! 0 ! clicks 

! l=async! ! 

+—-—------- 5 sieaiaienieneatenetnes t---- oH +-------- 
4 Swl 

+--~-~--- : siaaieataaiedeataietan +—-----3--- $--~------ 
8 fnum 

+—-------- +—-------- +—-------- +-—------ 
12 ! mask 

+-------- +-------- +——--~----- +—-—------- 
16 ! state 

+-------- to--- +—-—------- +—-—------- 


7.3 BWAIT 


7.3 BWAIT 


Parameters: 


clicks 


fnum 


mask 


state 


Return Code: 


ret 
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Number of times the mouse enters this state within 
the “click interval” set up in the MOUSE Table after 
this call is made. If clicks is 0 and the mouse is 
already in this state, the event is already complete. 
A maximum number of 255 clicks is allowed. 


Mouse file number 


Bit mask of buttons to consider. The lowest order 
bit is set if the first mouse button to the left ts to 
be considered. The second lowest bit corresponds 
to the second button from the left. A total of 16 
mouse buttons can be supported in the low word of 
mask. 


Bit mask of buttons that define the button state 
given the mask that determines the buttons to 
ignore all together in the low word of state. The 
event will complete on any of the_ following 
conditions: 


@ when the number of clicks is Satisfied 


@ when the number of clicks is not satisfied but 
the timer interval elapses (see MOUSE Table, in 
Section 8). 


@® when the number of clicks = O and the button 
is in the state requested 


<n ee eames Ee ee ene me ne emmy ce cme cote eS meee ee memes eee me eects | me nem et cement tems ame ne eee 


Error Code 


Description: | 
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The BWAIT SVC allows the calling process to wait 
until a mouse button state is reached. The mask 
determines the number of mouse buttons the calling 
process wants considered. For example, by setting 
the mask appropriately, a one button mouse can be 
expected when there is more than one button. 


The clicks field allows the cailing process to receive 
multi-click mouse input. When a user presses a 
mouse button, releases it and presses it again 
within the “click interval”, the mouse has been 
double clicked. 


If clicks is set to two, and a second click is not 
performed within the “click interval”, the event is 
considered complete. The return value indicates the 
number of clicks actually performed and the last 
valid state of the buttons at the time of completion. 
lf clicks is set to zero, BWAIT returns a zero if the 
button state is already in the specified state. 
Otherwise, it returns one upon the first entry to the 
State. 


The “click interval” is changed in the MOUSE table 
through the SET SVC. 
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7.4 CANCEL 


C interface: 


LONG 
LONG 


dmask = 


dmask = 


Parameters: 


events 


Return Code: 


dmask 


Description: 
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dmask; 
events; 


s_cancel(events); 


__osif(F_CANCEL,events); 


Logical OR of event masks to be canceled 


Bit map of events that could not be canceled 
because they have already completed 


The CANCEL SVC terminates one or more specified 
asynchronous SVCs. The events argument is the 
logical OR of the event masks you want to cancel. 
The dmask return code indicates events that, 
although requested for termination, had already 
completed. Use the RETURN SVC to get the return 
codes for these events so the event bits can be 
reused. | 
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Parameters: 
flags 
SWi 
command 
buffer 


bits 0-3 are reserved 


bit 4: 1 = No new process (set bit 5 to 1) 
QO = New process (ignore bit 5) 


bit 5: 1= Chain | 
O = Not implemented (returns E_IMPLEMENT error) 


tt 


bit 6: reserved (must be 0 ) 


bit 7: 1 = Assign a new process family ID (FID) 
O = Keep the current process family ID (FID) 


It 


bits 8-12 are reserved (must be Q). 


bit 13: 1 = Force case to media default 
0 = Do not affect name case 


bit 14: 1 = Literal command 
O = Prefix substitution allowed 


ui 


bit 15: reserved (must be QO) 


Address of a software interrupt routine 


Address of 128-byte,  null-terminated — string 
indicating the name of the loadable file. 


Address of a variable length buffer containing a 
128-byte, null-terminated command tail and special 
information to be passed to the new process. (At 
most, the command tail can be 127 characters and 
one NULL byte long.) COMMAND puts the tail in the 
CMDENV table. Data after the first 128 bytes is put 
in the process's heap. 


COM 


MAND 


bufsize 


procinfo 


pid 
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The PROCESS table contains the heap address and 
size. Use this buffer area to pass an environment 
string, common data, or special information to the 
program. 


Size of buffer in bytes 


Address of the PINFO table. PINFO must be 
constructed as follows: 


+-------- +-------- +—-—----- +-—------- + 
0 ! ! 
Bs NAME + 
4 ' ' 
+ +—-------- +—-------- + 
8 ! ' PRIOR 'reserved'! 
+-------- +-~------- ‘$}----- +—-------- + 
TZ ' MAXMEM ' 
+-------- +—-------- +—-------- +—-------- + 
16 ' ADDMEM ' 


+-------- +—-—------- +—--+----- +—-------- + 


20 = Length in bytes 
name: Process name 


prior: Process priority (user processes are usually 
set to 200) 


maxmem: Maximum memory this process can own 
(larger minimum requirements specified by the 
command file supercede this amount) 


addmem: The amount of memory to be added to 
the minimum amount specified by the command file 
(FlexOS allocates the greater of the two values: 
maxmem or the sum of the command file’s specified 
minimum plus addmem) 


Address of new process ID. COMMAND puts the 
new process’s 32-bit PID at this location when flag 
bit 4 equals QO and COMMAND is_ called 
asynchronously. 


a 


rte: serene ets en te Ane SRNR ht ney re Sse AREF 


LONG fnum; 
UWORD nranges; 
UWORD flags,beg1,beg2,beg3,beg4; 
UWORD end1,end2,end3,end4; 
RECT region; 
ret = s_kctrl(fnum,nranges,beg1,end1,beg2,end2,...end4); 
ret = s_mctri(fnum,region); 
ret = s_gmctrl(fnum,region); 
ret = __osif(F_KCTRL,&parmblk); 
parmblk: 
t+--- t salient alinedinedineiesietiantinntients sientaaentnatndientatnnts 4 
Q) t () ! () : flags : 
So tome ee ree : aiatinaientenieatnatontion : sloetieatientnentiniantentbed + 
4 0 
 slieeeitientieliaatientiatiianti sitaiiaiiatticatieetitaatien stedestenteniertenticadneds dhetedntedetedtentends 2 
8 ! fnum : 
a a ead ead aa 
12 ' beg! ' end | ' 
be ee hee re rr eH te eH ee et 
16 ' beg? ' end2 ! 
tae eb re re pe eH ee He ot 
20 ' neg ' end3 ' 
+o ee toe oe ee +--- -- e e +-------- + 
24 : beg4 : end4 ' 
sa ice Re SR a a ac es + 
(if mouse control) 
pts i ea ee Se ee eo Se ~=—+ 
12 ROW COL 
Hmm ee ee re ee ee ee HH + 
16 NROWS NCOLS 
PSS ee Se aS +—-—-- +e See eee Pens Sees + 


C Interface: 


KCTRL 
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KCTRL 


Parameters: 


flags _ 


nranges 
fnum 


begn 


endn 


region 
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bit 0: 1 = Mouse control 


O = Character control 
bit 2: 1 = default region definition 
(ROW,COL,NROWS,NCOLS) 
0 = GEM-compatible region definition 
(COL,FROW,NCOLS,NROWS) 
If bit O = OQ, keyboard and mouse ownership is 


controlled through characters typed on the keyboard 
and the begin range and end range parameters are 
required. If bit O =1, keyboard and mouse 
ownership is controlled through mouse movement 
and a region is required. 


lf bit 2 = 0, the region is GEM-like. If bit 2 =1, the 
region has the default definition. 


The number of beginning and ending ranges to 
follow--maximum 4. 


Console file number of console to get keyboard; 
must be console file of the parent virtual console. 


First character in range of characters; pressing any 
character in range causes keyboard to return to 
specified console. 


Last character in the range. 


RECT structure defining a character rectangle on the 


parent’s virtual console. 


g a 
4 5 
t 


( 


Return Code: 


ret 


Description: 
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Error Code 


The KCTRL SVC transfers keyboard ownership to the 
console file specified by fnum when a character is 
entered that falls within any of the four ranges 
specified. The initial transfer of ownership is 
conferred with the GIVE SVC. 


You can specify up to four character ranges. The 
ranges are inclusive of the first and last characters. 
A single character is specified by using it as the 
beginning and. ending character. When a character 
falling in the range is typed, that character and all 
subsequent characters are diverted to the parent 
console file's keyboard buffer. The process 
controlling the virtual consoles can either give 
control of the keyboard to another virtual console or 
take some special action on behalf of the user. 


You can also use mouse position to change 
keyboard and mouse ownership. In this case you 
specify a RECT (see Section 3 for the RECT 
description) on the parent console in which the 
mouse form must be resident. This region must be 
within the virtual console. When the mouse leaves 
the region, keyboard and mouse ownership go back 
to the parent. This happens as long as the 
rectangle’s size is greater than 0. The parent's 
application must set NROWS and NCOLS to disable 
a previously defined s mctri if it wants to regain 
ownership whenever the mouse is outside the 
specified rectangle. 


s_kctrl and s_mctrl are disabled by reversing the 
order of the beginning and ending character ranges, 
or providing a rectangle of size 0. 
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7.22 LOCK 


C Interface: 


UWORD flags; 
LONG fnum,offset,nbytes; 


ret = s_lock(flags,fnum,offset,nbytes); 
emask = e_lock(swi,flags,fnum,offset,nbytes): 
ret = _osif(F_LOCK,&parmblk); 


parmbtk: 
+—-------- +-~------- +-------- +—-------- + 
0 ! Q=sync ! 0 ! flags ! 
! l=async! ! ! 
+—-—------- +—-—-—----- +—---—----- +—-~------- + 
4 ! Swl ! 
+—-——------ +—-—----~--- +-------- +—-------- + 
8 fnum ! 
+—-------- +-------- +—----—---- +—+------ + 
12 ! offset ! 
+—-------- +—-—------- +—-------- +—-------- + 
16 ! nbytes ! 
+-—------- +—-—------- +—-------- +—--—------ + 
Parameters: 
flags bits 0 and 1 select the LOCK mode 


Unlock 

Exclusive lock 
Exclusive write lock 
Shared write lock 


WN = © 
Wool 


bits 2-3 are reserved (must be 0) 
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7.23 LOOKUP 

C Interface: 
UWORD flags: 
BYTE _ table,“*name,*“buffer; 
LONG key, bufsiz,itemsiz,nfound; 


nfound = s_lookup(table,flags,name,buffer,bufsiz,itemsiz, key), 


ret = _ osif(F_LOOKUP,&parmblk): 


parmblk: 
+—-------- +—-------- +—-------- +——-------— + 
0 0 ! table ! flags ! 
+—--~~~---- +—--~----- +—--—---—-—-— +—-------- + 
4 ! 0 
¢ +-------- +—-------- +—-~------- +—-—------- + 
8 ! name ! 
+—-------- +—-------- +—-------- +—----—----— + 
12 ! buffer ! 
+---~----- +—-—-~------ +—-------- +—-------- + 
16 ! bufsiz 
+—-------- +—-—------- +-------- +—-----—---— + 
20 1tems1iz ! 
+-------- +-~-~------ +-------- +—-------- + 
24 ! key ! 
+—-------- +—-—------- +-------- +—-------- + 
Parameters: 
table Table Number (Table 10-1 lists the table numbers) 
( 7 flags bits 0 - 7 are dependent on table type 


bits 8 -12 are reserved (must be 0) 
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name 


buffer 
bufsiz 


itemsiz 


key 


Return Code: 


nfound 


ret 


7-64 


FlexOS Programmer's Guide 


=_ 


= Force name case to media default 


bit 13: 
. Do not change name case 


© 
Ht 


bit 14: 1 = Literal name 
O = Prefix translation allowed 


bit 15 is reserved (must be 0) 


Address of the table name to search for; names are 
case sensitive. 


Address of buffer to store information collected. 
Size of buffer in bytes. 


The number of bytes to store from each table. If 
itemsiz is less than the table size, only as many as 
complete fields from each table found are written in 
the buffer. If itemsiz is greater than the table size, 
the excess area is not modified. 


Key from. which to continue searching. The key 
value depends on the table type. Each table allowing 
LOOKUP specifies a key for continued search. The 
LOOKUP SVC continues the search from the first 
item after the key. A key value of O always starts 
the LOOKUP search from the beginning of the table. 


Number of tables found. LOOKUP stops searching 
when the end of the buffer is reached or there are 
no more tables. If the last table does not fit into the 
remaining buffer space, it is discarded. 


Error Code 


Van N 

, \ 

f 
\ 
\ 
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bit 4: 1 = Shared 
Exclusive 


© 
i 


bit 5: 1 = Allow shared reads if shared 
Allow shared R/W if shared 


© 
i 


bit 6: 1 = Shared file pointer 
Unique file pointer 


© 
i 


bit 7: 1 = Reduced access accepted 


Q = Return error on reduced access 
bit 8: 1 = Force logical remount 

0 = Do not force logical remount 
bit 9: 1 = Force physical remount 

0 = Do not force physical remount 


bits 10 - 12 are reserved (must be OQ) 


-bit 13: 1 = Force case to media default 
0 = Do not affect name case 


bit 14: 1 = Literal name 
O = Prefix substitution allowed 


bit 15 is reserved (must be QO) 
name Address of file, pipe, or device name 
Return Code: 


fnum file number 
ret Error Code 
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OPEN 


Description: 


7~72 
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The OPEN SVC opens an existing file and returns a 
32-bit file number used for subsequent I/O. “File” in 
this context refers to disk files, pipes, and device 
files used to communicate with printers, mouses, 
consoles, and special devices. FlexOS sets the file 
pointer to 0 when you open the file. 


Use flag bits 0 through 3 to request the file access 
privileges-—-read, write, execute, and delete/set. Use 
flags 4, 5, and 6 to set the access mode--shared 
versus exclusive, shared read only versus shared 
read/write when shared, and shared versus unique 
file pointer. The use of these flags to monitor file 
access differs slightly from one type of file to 
another. See the sections in this manual on disk 
file, console, pipe, and special device management 
for the description of flag use with these types of 
files. 


Set flag bit 6 when you want two or more 
processes to share the same file pointer; this 
feature is only available to processes with the same 
family identification number (FID). Each process 
sharing the pointer must have this flag set. When 
this bit is set, the value of flag bit 1 is assumed to 
be 1; the actual value is ignored. 


Set bit 7 to accept reduced access privileges. The 
file's governing privileges for Owner, group, and 
world categories are set when it is created. Reduced 
access is an issue when a disk label’s security flag 
bit is set and you request a privilege level not 
available to a process with your ID and group 
number. Set this flag to 1 if you can accept 
reduced access; FlexOS ANDs the file’s R, W, E, and 
D privileges corresponding to your category with 
those you requested to determine the privileges you 
actually get. Set this flag to 0 if you cannot accept 
reduced access; FlexOS returns an error code when 
the privileges do not match. 
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7.31 RETURN 


C interface: 


LONG 


emask: 


ret = s_return(emask); 


tH 


ret 
Parameters: 

emask 
Return Code: 


ret 


Description: 


__osif(F_RETURN,emask); 


Event mask of completed event 


return code of asynchronous SVC 


The RETURN SVC retrieves the return code of an 
asynchronous SVC. If the event is not complete, 
FlexOS waits for it to complete before returning 
from the RETURN call. Use WAIT or STATUS to 
determine if the event has completed. The return 
code is the code that would have been returned if 
the SVC had not been called synchronously. Once 
the RETURN SVC has been called, the event's emask 
bit is cleared. 


Note: You cannot use RETURN for events with a 
software interrupt (swi). The event’s completion is 
provided to the swi and ts not kept available to the 
parent process. 
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RWAIT 


C Interface: 


RECT 


position 
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“region; 


= s_rwait(flags,fnum,region); 


emask = e_rwait(swi,flags,fnum,region): 


ret = __osif(F_RWAIT,&parmblk); 


parmblk 
dee de. 
0 Oe 
ae 
Spire! 

4 
ata ce 

8 
fame 

12 ‘ 

" 

16 f 
ane 
Parameters: 

flags 


----- a oe oo. 

sync 0 : flags : 

async! : ' 

-~--+- ee en. 

Swi : 

----- +----- ---4+----- +--+ 

fnum i 

—---- ee es 

: 

region ! 

' 

--~--- + —-------+--—-- - - - +--+ 
bit 0: O = return on entry from rectangle — 


1 = return on exit to rectangle 


i) 


bit 1: = no clip 


clip to visible view of the window 


— | 
it 


bit 2: O = default region definition 
1 = GEM-compatible region definition 


bits 3-15 are reserved and must be 0. 


——, 
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fnum - File number of open mouse file 


region RECT structure describing a rectangular area of the 
screen associated with the mouse. 


Default region 


+--- + ~=+-------- se ee + 

lz ' row coiumn 
tae ee ee Re ee pe ee ee ee ee + 

16 ! NeOWS ' ncals ' 
Se ee eee +-------- + 


pe eee ee eS ee $—- eee ee Peewee + 
1? ' column ' row ‘ 
+ aia Raabe nai: Sade: Wynd Aden” slesee. oe “teak -ceane; Salat eM sida’ Shea paces” sear teal + Sec niente "diez SE pig; alin Sela Waban: <tadins aah seth y <Saceie  sateites, Reps “eat petal Sateen ing + 
16 y ncols ' nrows ' 
+ Baal ih ees, iat, Tikes eee He Sh + rhe : Soe : ot aks + ne fae ~ me wee ee + Raat eh aarti ote ears | tale ef as + 


Return Code: 


ret Error Code 


Position (see diagram below) 


" current cow (or column) | current column (or row) | 

Description: The RWAIT SVC allows a process to detect the 
mouse entering or exiting a described region of the 
screen. 


If bit 0 = 0, RWAIT checks only inside the current 
view on the screen. lf bit 0 =1, the rectangle can be 
outside the visible view to complete the event. 
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7.33 SEEK 


C Interface: 


LONG fnum, offset; 
UWORD flags; 


position = s_seek(flags,fnum,offset); 


ret = __ osif(F_SEEK,&parmblk); 


parmblk: 
$—-—-—-—---- $—-———----- pee ee ee $—-—------ + 
0 ! 0 ! 0 ! flags ! 
$——-—- $—-—-—------ $——-—-—----- +—-—--—----- + 
4 ! 0 ! 
+——------- $—-—-—-—----- $—-—-—-—--—--- $+—-------- + 
8 ! fnum ! 
+—-—------- $—-—-—----- $-------- $—-—------- + 
12 ! offset fl 
$+ +—-------- $—-------- $—-—------- + 
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7.39 WAIT 


( C Interface: 
LONG events.cmask: 
cmask = s_wait(events): 
ret = _ osif(F_WAIT,events); 
Parameters: 
events Logical OR of emasks to wai for 
Return Code: 
cmask Bit map of completed events 


Error Code e_emask if all the events are invalid © 


Description: The WAIT SVC causes the calling process to wait for 
an asynchronous event to occur. Specify one or 
more events by their emask in the WAIT events 
argument. FlexOS returns when one of these events 
has run to completion. For events that do not have 
a software interrupt, the cmask return’ code 
indicates which event completed. Subsequently, call 
the RETURN SVC to retrieve the return code of the 
completed event. This also releases that emask so 
it can be reused. 


You can wait on events that have a_ software 
interrupt (Swi). However, the event bit in the cmask 
a returned is 0 rather than 1 when WAIT returns. Also, 
( do not call RETURN to retrieve the completion code 
rs after WAIT returns--the completion is no longer 
available having already been provided to the swi 
for handling. 
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‘If multiple events are being waited on and one or 
more are invalid they are ignored. If they are all 
invalid, an error E_LEMASK is returned. | 
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7.40 WRITE. 

C Interface: 
LONG fnum,bufsiz,offset,nbytes; 
BYTE option,”“buffer; 
UWORD flags; 


nbytes = s_write(flags,fnum,buffer,bufsiz,offset); 
emask = e_write(swi,flags,fnum,buffer,bufsiz,offset); 


ret = __osif(F_WRITE,&parmblk); 


parmblk: 
+—-------- +—-—------- +—-—--—---- +—-—-~—-~-~- + 
0 ! O=sync ! option ! flags ! 
! l=async! : ! 
+—---- eH $—-------- +——------- +—-—-—~----- + 
4 Swl ! 
+—-------- $+—-------- +—-—------ +—-------- + 
8 fnum ! 
+—-------- $+—-------- +—-------- +—-------- + 
12 buffer ! 
+—--~------ +-------- +—-------- +—-—---~—--- + 
16 ! bufsiz ! 
| +—------- +—-------- +—--—------ +—-—------- + 
20 ! | offset ! 
+—-------- +-------- +—-------- +—------—-- + 


7-118 


SECTION 8 


reenemenreeaennetcte enen a ee tg aR es RNR 


System Tables 


System status and parameter values are available to applications 
through the GET, SET, and LOOKUP SVCs which operate on a set of 
formalized data structures that comprise FlexOS’s system tables. This 
section presents descriptions of the system tables in alphabetical 
order. 


The GET SVC transfers the table to a buffer in the application’s 
memory space. The SET SVC changes values in a table. For both 
SVCs, the table is identified by its number and, when that table type 
has more than one version, a unique ID number. The LOOKUP SVC 
searches for and retrieves tables of the same type. Each table that 
can be accessed with LOOKUP has a key value field; use this field to 
specify a starting point for the search. 


The GET, SET, and LOOKUP SVCs will not access all of the system 
iabies. Tabie 8-71 lisis e@acn of the system tables and the SVCs used 
to access them. Also listed in Table 8-1 are each table’s number, ID, 
and key value. 


System Tables 


Table No. 
& Name 


OH PROCESS 
1H ENVIRON 
2H TIMEDATE 
3H MEMORY | 
1OH PIPE 
2ZOH DISKFILE 
21H DISK 


30H CONSOLE 
ole -PGONSOLE 
32H VCONSOLE 
33H MOUSE 
40H SYSTEM 
41H FILNUM 
4A2H SYSDEF 
43H PROCDEF 
44H CMDENV 
45H DEVICE 
46H PATHNAME 
71H PRINTER 
75H MOUSE DT 
81H PORT 
B2H+ SPECIAL 


GET Se 
Xx x 
Xx Xx 
Xx x 
x 
X 
Xx x 
Xx x 
x Xx 
Xx x 
Xx x 
Xx X 
xX Xx 
Xx 
X 
Xx x 
Xx Xx 
Xx x 
x x 


Table 8-1. 


Unique LOOK 


ID 


pid 
O 

O 

OQ 
froum 
fFoum 
fmum 
foum 
fou 
fnum 
fnum 
QO 
fnum 


pid 


f num 
fnum 
fnum 
fnum 
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System Table Access 


UP 


In the following system table descriptions, only those fields marked 
R/W are read-write; all other fields are read-only. In all bit-mapped 
values the bits for which there are no options are reserved and must 


be 0. 


Note: FlexOS does not maintain memory representations for the 
tables described in this section. 
or driver constructs them only when you call the GET, SET, or LOOKUP 


SVCs. 


8-2 


Key Description 
pid Process information 
Process environment 
System time of day 
System memory use. 
key Pipe information 
key Disk file information 
Disk device information 
Console file information 
Console device information 
VCNUM Console information 
Mouse information 
Global system information 
fnum File number’s table 
key System logical name table 
key Process logical name table 
Command environment 
key Device information 
none Full path name 
Printer device information \ 
Mouse driver table information — 
Port device information 
Special device information 
The corresponding resource manager 
# 
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@® KMODE (R/W): Keyboard mode 


bit 0: 1 = Disable Control-C 
0 = Control-C attempts external abort 


bit 1: 1 = Disable Control-S/Control-Q 
0 = Allow Control-S/Control-Q 
bit 2: 1 = Disable keyboard s_xlat translation table 
0 = Translate keys 
bit 3: 1 = Disable ESC sequence decoding 
0 = Support ESC sequence 
bit 4: 1 = Characters are 16-bit values 
0 = Characters are 8-bit values 


bit 5: 1 = Disable echo 
0 = Echo input characters on screen 


a bit 6: 1 = Disable CTRL-Z 
= CTRL-Z = end of file 


© 
l 


bit 7: 1 = Enable toggle characters 
0 = Disable toggle characters 


bit 8: 1 = Convert <LF> or <CR> to <CR><LF> 
0 = Do not convert <LF> or <CR> 


bit 9: 1 = Do not echo carriage returns 
0 = Echo carriage returns 


bit 10: 1 = Do not echo <CR> on any delimiter 
0 = Echo <CR> on any delimiter 


@® CURROW (R/W): Current cursor row position 
@® CURCOL (R/W): Current cursor column position 
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® NROWS: Height of virtual screen in character rows 
® NCOLS: Width of virtual screen in character columns 
@ VCNUM: Decimal number of virtual console 


@ TYPE: Type of virtual console 


bit 0: 1 = Graphics capability 
0 = Character only 


bit 1: 1 = No numeric keypad 
O = Keypad 
bit 2: 1 = Mouse support 
~ Q = No mouse support 
bit 3: 1 = Color 
0 = Black and white 
bit 4: 1 = Memory-mapped video 
0 = Serial device 
bit 5: 1 = Currently in graphics mode 
0 = Currently in character mode 


@ CNAME: Physical console device name 


Each console file opened has a corresponding CONSOLE table. The 
TAHEAD, CURROW, and CURCOL values are initialized to 0 when the 
console file is opened. NROWS and NCOLS correspond to the rows and 
columns set in the virtual console. SMODE and KMODE are initialized 
to 0; TYPE and CNAME are inherited from the parent console. 


GET and SET the CONSOLE table using as the ID the file number 
returned when you OPENed the file vcxxx/console. Do not use the file 
number returned when you CREATEd the virtual console. For most 
applications, this file number is contained in the stdout--the screen 
file number--and stdin--the keyboard file number--in the ENVIRON 
table. Stdin and stdout can have the same or different file numbers. 


Use SET to change the cursor position and the screen and keyboard 
modes. 


8-6 


FlexOS Programmer's Guide DEVICE Table 


@® INSTAT: Installation status 


0x00 - Not installed 

0x01 - Requires subdriver 

0x02 - Owned by the Miscellaneous Resource Manager 
0x03 - Owned by another driver 

0x04 - Optional subdriver 


@ OWNERID: Significant 16 bits of the key field of the owner's 
DEVICE table entry. Use this value with a LOOKUP to find the 
driver that owns this subdriver. This field is only valid when 
INSTAT has a value of 0x03. 


The DEVNAME, TYPE, ACCESS, and KEY values are established when 
the device is installed and do not change. The ACCESS flags override 
conflicting requests made by programs when they open the device. 


The INSTAT and OWNERID values are also static except for subdrivers 
assigned to different drivers. In this case, the current values are 
Subject to change as the driver is linked and unlinked to different 
owners. | 


You must use the LOOKUP SVC to get DEVICE tables. Wildcards can be 
used in the LOOKUP device name specification. 
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8.4 DISK Table 


Number GET? SET? LOOKUP? 
21H ~~~ Yes Yes No 


ID: File number returned by OPEN 
Key: none 


The DISK table describes a disk driver. All fields are read-only except 
the label options. 
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8.9 MOUSE Table 


Number GET? SET? LOOKUP? 
33H Yes Yes No 


ID: File number returned by OPEN 
Key: none 


The MOUSE table describes a pointing device. Every installed pointing 
device has a MOUSE table. The initial values are set by the driver and 
you can set all of them except for the PIXROW and PIXCOL. 


() 1 2 3 
() oft Fd ee ahh ee 9 cet ea es ee Se ee nce he et Sees ee Se 
' ROW COL 
Des ~ Recep eee aes ee ee Cre Ne ee a 
'KEYSTATE!RESERVED| BUTTONS 
A Hf ae sh eae en ee a ce Ge Se ae et ae ee ae 
PIXROW PIXCOL 
Lk Ae Ee, Hine eb ee rte fee Ae Se ee + 
CLICKTIME ' HEIGHT ! WIDTH ! 
Loo fee ees See fe See ei C2 2S aS ee + 
. HO TROW HOTCOL 
4 QE)! eS Be > a Se es ee a Sea ae eas +~—------- + 
- 4 MASK (16 words) + 
A? ae Sa ee te ae a eS ee fe + 
+ DATA (16 words) + 
Bal Be Se oor Sac Ee arate ard pret Se RS a aor pi ec + 


@ ROW (R/W): Current row position of mouse 


® COL (R/W): Current column position of mouse 


8-23 


MOUSE Table | FiexOS Programmer's Guide 


@ KEYSTATE: Keyboard: state of the right Shift, left Shift, Control, 
and Alt keys a : 


Bit 0 right Shift key 
Bit 1 left Shift key 

Bit 2) Control key 
Bit 3 Alt key 


0. - up position 
1 - down position 


@ BUTTONS: The least significant bit is the leftmost button. Total 
buttons supported is 16. 


PIXROW: Number of mickeys per pixel for rows 

PIXCOL: Number of mickeys per pixel for columns 
CLICKTIME (R/W): Click interval in milliseconds (usually 174) 
HEIGHT (R/W): Height of mouse form 

WIDTH (R/W): Width of mouse form 

HOTROW (R/W): Hot row of mouse form 

HOTCOL (R/W): Hot column of mouse form 


MASK (R/W): On a bit map screen, a 16 x 16 pixel rectangle that 
masks the effect of the DATA rectangle. 


DATA (R/W): On a bit map screen, a 16 x 16 pixel rectangle to 
“BLT” to the screen given the mask. 


The ROW and COL values are updated by the Console Resource 
Manager to indicate the current mouse location. You can, however, set 
these values to move the mouse form to a location without device 
input. The HEIGHT and WIDTH values have a maximum value of 4, but 
can be less. If either is less, the length of the MASK and DATA fields 
is not affected. 
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8.9a MOUSE DRIVER Table 


Number GET? SET? LOOKUP? 
( | 75H Yes Yes No 


ID: File number returned by OPEN 
Key: none 


The MOUSE Driver is a device driver for a pointing device such as a 
mouse, tablet, touch screen, light pen, joystick, or other similar device. 
Every installed pointing device has a MOUSE Driver table. Normally, a 
MOUSE Driver is optionally owned by the console driver as a 
subdriver. The MOUSE driver itself requires a PORT subdriver to 
connect to the physical I/O port. 


After loading and linking a PORT Driver, the MOUSE Driver is owned by 
the Resource Manager and then you can use GET and SET on this 
table. However, after the MOUSE Driver is linked to and optionally 
owned by a CONSOLE Driver, this table is inaccessible. 


The CONSOLE Driver sets the ROW MAX and COL MAX values for 
maximum resolution in graphics mode (e.g. 640 x 200) using a SET call, 
then makes a GET call to read the values for BUTTONS, PIXROW, and 
PIXCOL from the MOUSE Driver. 


Note: All row and column values are absolute pixel values of the 
physical screen. 


Sample installation script: 


dvrload mouseOQ: hdO:\drivers\mdrv.drv Inrws ;load the mouse driver 
dvrlink mouseQ: ptQ: ;link it to serial port O 
dvrlink conO: mouseOQ: smake mouse driver a subdriver 


sof the console driver 


if you want to connect it to serial port 1; 


dvruntik mouseQ: sunlink driver from console 
dvrload mouse(: hdO:\drivers\mdrv.drv Inrws ;load the mouse driver again 
dvrlink mouseO: ptt: slink it to serial port 1 
_ dvrlink con0O: mouseO: ;make mouse driver a subdriver 
( | | :of the console driver 
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Salata aetieeiaeetienstiatinetontianionteatnenimainedietindatiatiantenion $2 SSS SS Se odienientiaainetaien + 
| ROW MAX | COL MAX | | 
| RESERVED | NUM BUTTONS | 
| PIXROW | PIXCOL | 
| DOUBLE _Y | DOUBLE X | 
| CURRENT ROW | CURRENT COL | 
| + BUTTON STATE | | RESERVED | 
$m RR RS RS ee » sleeeaiteniaatientiaetiontintantineteatnentnadteatimatmetiantantineantatentnetteaina + 


ROW MAX (R/W): Maximum value of row position of MOUSE in 
pixels | 


COL MAX (R/W): Maximum value of column position of MOUSE 
in pixels 


NUM BUTTONS: Number of buttons supported by driver 
PIXROW: Number of internal pixels for one row (set by driver) 
PIXCOL: Number of internal pixels for one column (set by driver) 


DOUBLE VY (R/W): Double the internal delta y values when bigger 
than this value. Optimized for quicker mouse movement 


DOUBLE X (R/W): Double the internal delta_x values when bigger 
than this value. Optimized for quicker mouse movement 


CURRENT ROW: Current row position, valid values are 0 to 
ROW MAX 


CURRENT COL: Current column position; valid values are 0 to 
COL MAX 


BUTTON STATE: Current button state. Each bit represents a 
mouse button, with the least significant bit representing the 
leftmost button. 


bit = O button not pressed 
bit = 1 button pressed 
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8.10 PATHNAME Table 


Number GET? SET? LOOKUP? 
46H No No Yes 


ID: none 
Key’ none 


The PATHNAME table contains the fully-expanded path name for a 
defined symbol. LOOKUP is the only way to retrieve a PATHNAME 
table; you cannot SET or GET a PATHNAME. 


0 1 2 3 

+—-------- +—-— eee +-—-- 3 +-------o- + 

QO ! 

+ PATHNAME + 

4 ! 

124 ! ! 

+—- eo ee +o +--— 3  slieaealanatiaentietnenstnentamntmentneans + 
19Q Tananth a Avert ne 
LZo BENGteN if OYCTES 


The PATHNAME table consists of a single 128 byte field. Only one path 
is ever returned when you lookup a defined symbol. If the symbol 
specified starts with a defined name, the prefix is substituted for the 
symbol. If the first name in the prefix is itself a defined symbol, the 
substitution is made again. The search and substitute routine is 
repeated until no prefix is found for the starting name. 


The SYSDEF and PROCDEF tables are searched when you lookup the 
PATHNAME table. (DEFINE only looks in one or the other.) These 
tables are searched for the first name in the specification only. 


Wildcard characters can be used but they are not expanded; for 
example, as asterisk is interpreted only as an asterisk. 
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8.11 PCONSOLE Table 


Number GET? SET? LOOKUP? 
31H Yes Yes No — 


ID: File number returned by OPEN 
Key: none 
The PCONSOLE table describes a physical console device. Each 


console installed has its own PCONSOLE table. All parameters are 
read-only except the country code. 


0 2 3 
+—------ +-—-------- $+—-------- +--~------ + 
() ' ' 
+ NAME + 
4 ' ! 
+ +-—---- 7-H +—-------- + 
8 : ' NVC ! CID ' 
+--+ = K +-------- +#—--~------ +----- + - + 
io- -2 ROWS COLS 
+—---- 3 +-—------ +—---+---- +—-------- + 
16! CROWS CCOLS a 
ies accent oe era aa ae nS a ae eee rea + : 
IG. 2 TVPE ' PLANES ! ATTRP ! EXTP ! See 
+—---—------ +—-----~--- +--+ - 3+ +—--+-----+- + 
24 ! COUNTRY ' NFKEYS 'BUTTONS ! 
+—-------- t------ OH +—-------- +—-------- + 
28 ' SERIAL # ! 
+—-------- +---~---- +-----~-- +—-------- + 
32 ! MUROW : MUCOL ! 
$m ee ee saieeticadianstineaticatiedaaattenientatentnattanteanantatanteantiee + 
40 ' CHARHE [I GHT CHARWIDTH 
+—-—------- +-------- + --~------ +—-~------- + 
40 = Length in bytes 
@® NAME: Console device name 
@® NVC: Current number of virtual consoles 
@® CID: Physical console ID number 
ye 
9 
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® ROWS: On graphic console devices, this is the number of rows of 
pixels. On character console devices, this is the number of 
character rows and is the same as CROWS. 


@ COLS: On graphic console devices, this is the number of pixels in 
a row. On character console devices, this is the number of 
character columns and is the same as CCOLS. 


® CROWS: The number of rows of characters 
@® CCOLS: The number of columns of characters 
@® TYPE: Type of console | 


bit 0: 1 = Graphics capability 
Q = Character only 


bit 1: 1 = No numeric keypad 


Q = Keypad 
bit 2: 1 = Mouse supported 
0 = No mouse supported 


bit 3: 1 = Color 
O = Black and white 


bit 4: 1 = Memory-mapped video 
O = Serial device 


bit 5: 1 = Currently in graphics mode 
O = Currently in character mode 


@ PLANES: Planes supported 
Bit O: 1 = Character plane supported 


O = No character plane 
Bit 1: 1 = Attribute plane supported 
0 = No attribute plane 
( y Bit 2: 1 = Extension plane supported 
= 0 = No extension plane 
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@ ATTRP: Bit map of attribute plane bits supported 
@ EXTP: Bit map of extension plane bits supported. 


@ COUNTRY (R/W): Country code; in applications that support 
multiple character sets, use this value to select a specific set. 
Appendix C lists the country codes. 


NFKEYS: Number of function keys supported 
BUTTONS: Number of mouse buttons supported 
SERIAL #: Mouse serial number 

MUROW: Mouse sensitivity in mickey units per row 
MUCOL: Mouse sensitivity in mickey units per column 


CHARHEIGHT: Height of character cell in pixels 


CHARWIDTH: Width of character cell in pixels 


The PCONSOLE values are set by the driver. The Console Resource 
Manager updates the NVC value as you create and delete virtual 
consoles on this console. 


To GET and SET a PCONSOLE table (LOOKUP cannot be used), OPEN 
the device and use the file number returned as the GET and SET ID 
number. In your OPEN call, the only access mode flag bit you can set 
is bit 0 and you only need set it if you want to change the country 
code. 
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8.20 TIMEDATE Table 


Number GET? SET? LOOKUP? 
2H Yes Yes No 


ID: 0 

Key: none 

The TIMEDATE table contains the system time of day. All fields are 
read/write except WEEKDAY. The time is maintained by the kernel once 
the starting is set. Use SET to establish the starting time. 


0 1 2 3 
+—-------- +-------- +—-------- +—-------- + 
O ! YEAR ' MONTH ! £4DAY ! 
+-------- +—-—------- +—-------- +—-—-—------ + 
4 ! TIME 
+—-------- +—--~----- +—-—------- +—-—-—------ + 
8! TIMEZONE ! WEEKDAY! Reserved! 
+---~----- +---—----- +—-—------- +-------- + 
12 Length in bytes 


@ YEAR (R/W): Year; a literal value (for example, 1987 = 1987) 
@ MONTH (R/W): Month; 1 - 12 
@ DAY (R/W): Day of the month; 1 - 31 
@ TIME (R/W): Number of milliseconds since midnight 
@ TIMEZONE (R/W): Minutes from Universal Coordinated Time 
@® WEEKDAY: Day of the week; 0 = Sunday, 6 = Saturday 

You use an ID value of 0 to GET and SET the TIMEDATE table. 


a ae 
: \ 
aes WA 
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8.21 VCONSOLE Table 


Number GET? SET? LOOKUP? 
32H Yes Yes Yes 


ID: File number returned by CREATE 
Key: VCNUM assigned when virtual console created 


The VCONSOLE table describes a virtual console. Table values are 
established when you CREATE the console. Use read/write fields to 
modify window size, location on the virtual console, and placement on 
the parent console. 


0 1 2 3 
$--S--S $e ee +-—------- + + 
O ! KEY 
t-------- $+ - eee $e fess eS + 
4 ! MODE ! VCNUM ! TYPE ! 
+-—--—----— +-— +-—-—------ : sioledieaeiaetoasietanion + 
8! VI EWROW ! VIEWCOL 
, SRaBacansias cage cad acipaiic os, Sean aa ac 5 siento onion a a ose sie ate + 
12 ! NROW ! NCOL ! 
$5555 $m ee +—-—- ee a + 
16 ! POSROW ! POSCOL ! 
4-526 3= + fe SSS eS : siaesea a ears aa + 
20 ! ROWS ! COLS ! 
Fa a a Poses a aed SS lacs rl + 
24 ! TOP ! BOTTOM ! LEFT ! RIGHT ! 
+—-—--- ee +—--—------ +-—---—---- s eoelaealeetaaetanmation + 


28 = Length in bytes 


® KEY: Key field for LOOKUP 


8-44 


FlexOS Programmer's Guide VCONSOLE Table 


@® MODE (R/W): Window mode 


bit 0: 1 = Freeze borders 


0 = Synchronize borders (See Note 1, below) 

bit 1: 1 = Allow auto view change (See Note 2, below) 
0 = Keep view fixed 

bit 2: 1 = Keep cursor on edge on auto view change 
0 = Center cursor on auto view change 


bit 3: 1 = Auto view change on output 
0 = Auto view change on input 


® VCNUM: Decimal virtual console number 


@ TYPE: Type of console. 


bit 0: 1 = Graphics capability 
0 = Character only 


| 


bit 1: 1 = No numeric keypad 


{ QO = Keypad 
bit 2: 1 = Mouse supported 
0 = No mouse supported 
bit 3: 1 = Color 
0 = Black and white 
bit 4: 1 = Memory-mapped video 
0 = Serial device 


bit 5: 1 = Currently in graphics mode 
0 = Currently in character mode 


@ VIEWROW (R/W): Row coordinate on the virtual console view 
upper lefthand corner | 


( @ VIEWCOL (R/W): Column coordinate on the virtual console view 
ea upper lefthand corner 3 
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NROW (R/W): Number of character rows of the view 
NCOL (R/W): Number of character columns of the view 


POSROW (R/W): Row coordinate on parent virtual console of view 
upper lefthand corner 


POSCOL (R/W): Column coordinate on parent virtual console of 
view upper lefthand corner 


ROWS: Number of character rows in the virtual console 
COLS: Number of character columns in the virtual console 
TOP: Height in character rows of the top border 
BOTTOM: Height in character rows of the bottom border 
LEFT: Width in character columns of the left border 


RIGHT: Width in character columns of the right border 


Notes: 


1. 
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Use bit 0 to freeze a border so that intermediate states are not 
displayed when you make changes to the border file contents. 
Before you change the border file contents, set this bit. After you 
have completed the changes, reset the bit. Normally, keep this 
flag at O so that the borders change as you make changes to the 
window dimensions and location. 


. Bits 1 through 3 determine whether the window view changes to 


keep the cursor on-screen or the view remains fixed on the same 
virtual console coordinates regardless of cursor location. If the 
cursor leaves the window and bit 2 = 1, bit 3 determines whether 
the view changes when the cursor leaves the view (output) or 
when the application READs the keyboard. 
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Table B-2. Low-order Word Error Code Ranges 


Error Code Range Source 
0000 - 3FFF Drivers 
4000 - 407F Errors Common to All Resource Managers 
4080 - 40FF Supervisor 
4100 - 417F Memory 
4180 - 41FF Kernel 
4200 - 427F Pipe and Miscellaneous Resource Managers 
4280 - 42FF Console System 
4300 - 437F File System 
4400 — FFFF Reserved 


For the source of one of the common error codes, see the low byte in 
the high order word. The remaining tables in this appendix list define 
the error messages by their source. No error codes are currently 
associated with the Pipe, Console and Miscellaneous Resource 
Managers. 


B-3 


B Error and Return Codes 


Table B-3. 
Mnemonic Code 
E_WPROT 0x00 
E_UNITNO 0x01 © 
E READY — 0x02 
E_INVCMD 0x03 
E_CRC 0x04 
E_BADPB 3 0x05 
E SEEK | - 0x06 
E UNKNOWNMEDIA 0x07 
E SEC_NOTFOUND 0x08 
E DKATTACH 0x09 
E WRITEFAULT Ox0A 
E READFAULT Ox0B 
E_ GENERAL Ox0C 
E MISSADDR Ox0D 
E NEWMEDIA OxOE 
E DOOROPEN OxOF 


FlexOS Programmer’s Guide 


Driver Error Codes 


Description 


Write protect violation 
legal unit number 

Drive not ready 

Invalid command tssued 
CRC error on I/O 

Bad parameter block 

Seek operation failed 
Unknown media present 
Requested sector not found 
Attachment did not respond 
Write fault 

Read fault 

General failure 

Missing address mark 

New media detected 

Door has been opened 


es 
f : > 
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Table B-4. 


a ; Mnemonic 


E_SUCCESS 
F_ ACCESS 


E_CANCEL 
E_EOF 
E_EXISTS 
E_DEVICE 


E_DEVLOCK 
E_FILENUM 
E_FUNCNUM 
E_IMPLEMENT 
E_INFOTYPE 
E_INIT 

E CONFLICT 


E_ MEMORY 
E_MISMATCH 


E_NAME 
E_NO_FILE 


E_PARM 


E_RECSIZE 

—_ SUBDEV 
~ E_FLAG 

E_NOMEM 


i. 
: Aesroneeammnente 
( oe 
q ee, 


Code 


OxOL 
0x4001 


0x4002 
0x4003 
0x4004 
0x4005 


0x4006 
0x4007 
0x4008 
0x4009 
0x400A 
0x400B 


0x400C 


Wns 


0x400D 
Ox400E 


0x400F 
0x4010 


0x4011 


0x4012 
0x4013 
0x4014 
0x4015 
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Error Codes Shared by Resource Managers 


Description 


No Error 

Cannot access file--ownership 
differences 

Event Cancelled 

End of File 

File (CREATE) or device (INSTALL) exists 
Device does not match or not found; 
for RENAME, on different devices — 
Device is LOCKed 

Bad File Number 

Bad function number 

Function not implemented 

Illegal Infotype for this file 

Error on driver initialization 

Cannot access file due to current 
usage; for DELETE on open file or 
directory with files; for INSTALL, 
attempted replacement of driver in use 
Not enough memory available 
Function mismatch--file does not support 
attempted function; for INSTALL, mis- 
match of subdrive type 

ltlegal file name specified 

File not found; for CREATE, device or 
directory does not exist 

Illegal parameter specified; for 
EXCEPTION, an illegal number 

Record Size does not match request 
INSTALL only: Sub-drive required 

Bad Flag Number 

Non-existent memory 
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Mnemonic 


E_MBOUND 
E_ILLINS 
E_EDIVZERO 
E_EBOUND 
E_OFLOW 
E_PRIV 
E_TRACE 
E_BRKPT 
E_FLOAT 
E_STACK 
E_NOTON286 
E_EMI | 
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Table B-4. (Continued) 


Code. 


0x4016 
0x4017 
0x4018 
0x4019 


0x401A 


0x401B 
0x401C 
0x401D 
Ox401E 
Ox401F 
0x4020 
0x4021 


Description 


—_ 
| ( 
Memory bound error ae 
Ilegal instruction 
_ Divide by zero 

Bound exception 

Overflow exception 

Privilege violation 

Trace 

Breakpoint 

Floating point exception 

Stack fault 

General Exception 

Emulated instruction group 1 
Se 
ae, 
\ we 
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Table B-5. Supervisor and Memory Error Codes 


Mnemonic . Code 

E ASYNC 0x4080 
E LOAD 0x4082 
E LOOP 0x4083 
E_ FULL © 0x4084 
E DEFINE 0x4085 
E UNIT 0Ox4086 
E UNWANTED 0x4087 
E _DVRTYPE 0x4088 
E LSTACK 0Ox4089 


Memory Error Codes 


E POOL 0x4100 
E BADADD 0x4101 


Description 


Function does not allow 

asynchronous !/O 

Bad load format 

Infinite recursion (99 times) on prefix 
substitution; for INSTALL, subdrive type 
mismatch 

File number table full 

DEFINE only: illegal, or undefined name 
Too many driver units 

Driver does not need subdriver 

Driver returns bad driver type 

Stack not defined in load header 


Out of memory pool 
Specified bad address 


Mnemonic 


E_OVERRUN 
E_ FORCE 
E_PDNAME 
E_PROCINFO 
E_LOADTYPE 
E_ ADDRESS 
E EMASK 

E COMPLETE 
E_STRL 
E_ABORT 
E_CTRLC 
E_GO 
E_INSWI 


E_UNDERRUN 
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Table B-6. 


Code 


0x4180 | 


0x4181 
0x4182 
0x4183 
0x4184 
0x4185 
0x4186 
0x4187 
0x4188 
0x4189 
0Ox418A 
0x418B 
0x418C 
0x418D 


FlexOS Programmer's Guide 


Kernel Error Codes 


Description 


Flag already set 

Return code of aborted process 
Process ID not found on abort 
COMMAND only: no procinfo specified 
COMMAND only: invalid loadtype 
CONTROL only: invalid memory access 
Invalid event mask, or out of events 
Event has not completed 

Required SRIL could not be found 
Process cannot be terminated 
Process aborted by Ctrl-C 

Slave process running 

Not in SWI context; not a swi process 
Flag already pending 


Ky 


return 
exceptions: 


Mnemonic 


~ E_SPACE 


~ E_MEDIACHANGE 
E_MEDCHGERR 


E_PATH 


E_DEVCONFLICT 
E_RANGE 
E_READONLY 
E_DIRNOTEMPTY 
E_BADOFFSET 
E_CORRUPT 
E_PENDLK 
E_RAWMEDIA 
E_FILECLOSED 


E_LOCK 


E_FATERR 


codes, 
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Table B-7. Disk Error Codes 


Code 


0x4300 


0x4301 
0x4302 
0x4303 
0x4304 
0x4305 
0x4306 
0x4307 
0x4308 
0x4309 
0x430A 


0x430B 


0x430C 


0x430D 
0x430E 


Description 


Insufficient space on disk or in 
directory 

Media change occured 

Detected media change after a write 
Bad path 

Devices locked exclusively 

Address out of range 

RENAME or DELETE on R/O file 
DELETE of non-empty directory 

Bad offset in read, write or seek 
Corrupted FAT 

Cannot unlock a pending lock 

Not FlexOS media 

File closed before asynchronous lock 
could be compieted 

Lock access conflict 

Error while reading FAT 


Utility return codes follow the same format of operating system error 
illustrated 


in Figure B-1, with the _ following 


® Utility return codes are positive numbers (LONGS) because the 
high order bit (31) is always zero. 

® When possible, you should use the error codes listed in Table B-8 
in the error code field (bits 0-15). 

@® You can designate given modules within an application in the 


source field (bits 16-23). 
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To return errors generated within your application, OR the source field 
(module) with the error code field. For example, to indicate that an 
application has detected a parameter error, use: 


return( UR_SOURCE | UR_PARM ): 


Do not OR a source field value with UR_SUCCESS, which is a LONG of 
zeroes. ; ; 


Table B-8. Utility Return Codes 


Mnemonic Code Description 

UR_SOURCE (LONG)O Utility return 

UR_SUCCESS (LONG)O Success 

URPARM 0x0001 Parameter error 
UR_CONFLICT 0x0002 Contention conflict | 
UR_UTERM 0x0003 Terminated by user: > 
UR_FORMAT. 0x0004 Data structure format error 
INTERNAL 0x0005 Internal utility error 
UR_UR_DOSERR 0x0006 PC DOS error 


End of Appendix B 
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SECTION 12 


VDI Demo Programs 


Diskette PTK 3 contains three programs that demonstrate the 
Capabilities of the Virtual Device Interface (VDI): 


thing [ -| <# of points> |] 


This program draws a simple line-figure; it is useful for testing lines 
and line colors. The -! switch tells thing to draw a design with the 
specified number of points around the perimeter. By default, thing 
draws the figures with from four to ten points around the perimeter. 


polyline 
This program is documented in the GEM VDI reference manual. 
logos 


This program draws a number of Digital Research logos on the screen, 
using the copy transparent function, draws ORis siogan Over that 
using a one of the fonts loaded, and then cycles the colors on 16 
color screens (on an EGA device). 


All of these programs have the following switches in common: 


-f device Sends output to the specified device instead of the 
screen. 
-m | Emulate monochrome on color devices. 


-c colors number Set the maximum number of colors to the argument. 
If you specify too many colors, the number defaults 
to the maximum available. -m overrides this switch. 


End of Section 12 


121 


